Theme Asset Management

At a high level, when you work with themes, you create a theme using the Theme Generator. The theme you create should be based on the Core theme (or on another theme ultimately based on the Core Theme), which provides a robust foundation of functionality so you don't have to start from scratch when creating your theme. After you create your theme, you can edit the theme files, upload the theme to Dev Center, install it on a sandbox, modify the theme as needed, and publish the theme. 

Deploy to Production

It is possible to do self-serve production updates of themes, including pushing a theme from a sandbox to a production tenant. You must have followed the above steps to publish the theme first.

1. Find the theme that you are ready to deploy in Dev Center.
2. Click Install > Production Tenants in the menu.
3. Select the production tenant to deploy the theme to.
4. In the Admin UI of that production tenant, go to Main > Site Builder > Themes.
5. Find the version of the theme you just installed and expand the dropdown menu on the right hand side of its row in the themes table.
6. Click Apply. 

Your theme will now be fully applied onproduction.

Work on Themes as a Team

Whether you work on themes individually or as team, it is important to understand that you can use the Packages tab in Dev Center to organize your theme files into discrete packages. When a developer first creates a theme in Dev Center, the system automatically creates a Release package for the theme version. The benefit of creating additional packages, however, is that each developer can work on their theme features independently and test their themes on different sandboxes before merging the work of the entire team into the Release package.

Package Types

There are two types of packages in Dev Center:

• Release Packages: Release packages contain the production-ready assets that need to be published and certified in Dev Center prior to being installed on production.
• Development Packages: Development packages are conceptually similar to feature branches. Package names are appended to the Application Key of each package for identification purposes. The build tools rely on the Application Key to upload files to the right place in Dev Center

Development Modes

Until a developer uploads theme files, packages don’t contain any files; they act as containers for the theme files that change. The build tools upload the delta of changed files to Dev Center. When a developer is ready to publish a theme, the published code is contained in the release package. Developers work on a theme in either solo or team development mode.

Solo Development Mode

Solo development mode lets one developer work on one theme. In this mode, the recommended best practice is for the developer to store the base theme files in the release package and create a separate development package. Working in the development package lets the developer make changes without altering the base files. When the theme has been tested and is ready to be published, the developer uploads the production-ready files to the release package.

Team Development Mode

Team development mode lets multiple developers work on one theme by dividing the files between independently working developers; logically similar to feature branches. This mode works well in large companies and with solution or implementation partners. The recommended best practice is to store the base files in the release package and create separate packages for each developer.

The source control component of the file management process is handled outside Dev Center and is the task of the development team, but Kibo recommends using Git if possible. When all theme development is complete, the development team merges the file changes, uploads the final theme files to the release package, and publishes the theme.

Get Started with Team Development

The following tutorial provides a quick walkthrough of the team development workflow for themes:

In addition, this tutorial guides you through creating the initial theme record, scaffolding the initial project files based on the Core theme, and uploading these files to an online Git repository. If your team already has a theme repository to begin work off of, you can skip to the Create Development Packages for the Theme in Dev Center section of this tutorial.

Create the Parent Theme in Dev Center

In this section, you create the parent theme record in Dev Center. This theme record will contain all the packages associated with the theme your team works on, but in this section, you only create the release package:

The lead developer should:

1. Create a theme record in Dev Center.
2. Note the application key for the theme record.

Scaffold the Parent Theme

In this section, you create the initial version of the theme files that your team will then work on. You can install this theme to a sandbox of your choice for testing purposes:

The lead developer should:

1. Create a directory on your local machine in which to scaffold theme files.
2. Open a command prompt within the newly-created project directory.
3. Run yo mozu-theme to use the Theme Generator to scaffold a new theme. This is the parent theme from which all shared development packages will inherit and will become the release package in Dev Center. During scaffolding, select to:
   • Create a brand-new theme. If you are basing your work off a theme other than the Core theme, you would specify the repository for that theme instead.
   • Base the theme on the latest version of Core.
   • Enter the application key for the theme record you created in Dev Center. Because this is the parent theme, the application key should match the application key of the Release package.

If you want to test the initial version of the theme that your team will begin working off of:

1. After scaffolding is complete, run grunt in the project directory to build the theme files and upload them to Dev Center.
2. In Dev Center, install the theme to a sandbox.
3. View the sandbox and use Site Builder to enable the theme.

Create a Git Repository for the Parent Theme

Once you are happy with the initial version of the parent theme, make it available to your team members by connecting the local files with an online Git repository:

The lead developer should:

1. Create a Git repository to house your theme files on GitHub or a similar website.
2. Note the repository URL (for example, git@github.com:yourProfile/yourRepoName.git ).
3. Open a command prompt in your local theme directory.
4. Connect your local theme files to your online repository:
   1. Run git remote add origin yourRepositoryURL to add the remote repository.
   2. Run git push -u origin master to push your local files to the remote repository.

Create Development Packages for the Theme in Dev Center

When you are ready to begin developing as a team, create a separate theme package for each developer that will work on the theme:

The lead developer or each individual developer should:

1. In Dev Center, click your theme record.
2. Open the Packages tab.
3. Click New to create a new package for each developer working on the theme.

Complete Feature Work on the Different Theme Packages

Each developer can now work on their features for the theme within separate theme packages and Git repositories.

Each developer on your team should:

1. Navigate to the theme record in Dev Center.
2. Click the Packages tab.
3. Select the package you want to work on and note the application key. Make sure to note the application key for your development package and not the Release package.
4. To get the parent theme onto your local machine, you have two options: If you connect to your Git repository using SSH, the second option is recommended (cloning from Git). If you connect to your Git repository using HTTPS, both options work equally well.  Use the Theme Generator to scaffold theme files based on the parent theme's Git repository:
   1. Create a directory on your local machine in which to scaffold theme files.
   2. Open a command prompt within the newly-created project directory.
   3. Run yo mozu-theme to use the Theme Generator to scaffold a theme based on the parent theme. During scaffolding, select to:
      • Create a theme based on a repository URL (use the repository URL where the parent theme lives, as created in a prior section of this tutorial).
      • Enter the application key for the development package you want to work on.
5. Clone the parent theme repository using Git and then update the cloned theme files to point to your unique package application key:
   1. Navigate to a directory in which you want to pull down the Git repository folder.
   2. Open a command prompt within the directory.
   3. Run git clone yourRepositoryURL to clone the Git repository (use the repository URL where the parent theme lives, as created in a prior section of this tutorial).
   4. Change directories into the cloned theme folder.
   5. In the root directory of the cloned theme folder, create a new file called mozu.config.json and configure it as shown in the following code block, making sure to use the application key for your development package. To identify you developer account ID, click Launchpadunder your user name in Dev Center, and then hover over the link to the account you want to access. You should see your developer account ID appended to the URL, typically as a four-digit number. 
      clonedDirectory/ mozu.config.json 

      {
        "baseUrl": "https://home.mozu.com",
        "developerAccountId": yourDevAccountId,
        "developerAccount": {
          "emailAddress": "yourDevEmailAddress" 
         },
        "workingApplicationKey": "yourPackageApplicationKey" 
       }

   6. In the cloned directory, run npm install to install all the project dependencies.
6. After scaffolding is complete, create a Git branch for your feature work by running git checkout -b feature/branchName . Creating branches makes merging your changes easier down the line, and aligns with the organizational model in Dev Center, where development packages (your feature branches in Git) are kept separate from the Release package (the master branch in Git) until they are ready to be combined.
7. Run grunt in the project directory to build the theme files and upload them to Dev Center. Alternatively, run the grunt watch command so that any changes you make locally will be continuously synced with Dev Center. Just refresh your web browser to see the changes on your storefront. 
8. In Dev Center, select the package you are working on and install the theme to a sandbox. Each developer should use their own sandbox to prevent overwriting the theme files in another developer's sandbox.
9. View the sandbox and use Site Builder to enable the theme.
10. Modify the theme files as needed for your feature work. Test the theme changes in the storefront using grunt or grunt watch (recommended since it saves you the time of typing the command each time you make a change).
11. When you are done working on your feature, complete the following Git operations:
    • If you created new files, add them for tracking: git add -A
    • Commit your changes: git commit -a -m "Your commit message."
12. Because theme development might take some time, you can also push your ongoing feature commits to the remote repository to back up your work during development. 

Merge Feature Branches into Master

When all the developers on your theme are done with their feature work and made their final commit, it's time to merge the separate packages into the Release package:

Each developer on your team should:

1. Open a command prompt in your local project directory.
2. Run git checkout master to switch to the master branch.
3. Run git pull to obtain the latest changes to the parent theme.
4. Run git checkout feature/branchName to switch to your feature branch.
5. Run git rebase master to place your feature changes on top of what's in the master branch. You can also merge master into your feature branch, but in general, the rebase preserves a cleaner working history. For more information on the different merging strategies, refer to web articles on the topic.
6. Resolve any merge conflicts that may occur. The default Git merge tool can be difficult to use. Refer to web articles to learn about other merge tools available to you. 
7. Run git checkout master to switch to the master branch.
8. Run git merge feature/branchName to merge your feature branch into master.
9. Run git push to update the remote repository.

After every developer on your team completes this process, the master branch should contain the final version of the theme files, which includes everyone's changes.

Publish Your Theme in Dev Center

After you merge every feature branch into your master branch, upload the latest version of the parent theme to Dev Center and publish it:

The lead developer should:

1. Open a command prompt in your local project directory.
2. Run git checkout master to switch to the master branch.
3. Run git pull to ensure you have the final version of the parent theme.
4. Update the application key in mozu.config.json to use the Release package application key.
5. Run grunt to upload the theme assets to Dev Center.
6. In Dev Center, open your theme record.
7. In the Packages tab, select the Release package.
8. Spot-check the uploaded assets to ensure the final theme uploaded correctly to Dev Center.
9. Install the theme to a sandbox and test it to make sure you are happy with the final version of the theme. If you need to make changes, modify the theme files and use Git and grunt to commit and upload your changes before proceeding to the next steps.
10. (Optional Clean-Up) In the Packages tab, select each development package and click Delete to delete any package that is not the Release package.
11. In the Packages tab, select the Release package.
12. Click More > Publish to publish your theme. After you publish a theme, you cannot make further changes to the theme assets, including deleting packages. However, you can version a theme.