Development Workflow¶

Overview¶

The following page outlines a recommended Genesis, MMT, & Git workflows to illustrate best-practices that guide you through common tasks of feature development on a store.

Warning

The following guide assumes that you are familiar with the concepts descibed in the previous pages:

You have set up your development environment with the necessary prerequisites
You have installed Genesis on a Miva store
You have customized your Miva Admin
You are familiar with the steps involved in customizing, building, and deploying your CSS & JS
You have mmt installed and set up for your project so you can use it to customize templates.

1. Create a Production Sync¶

A production sync is a process to download all remote source-code changes into your local repo. They are especially helpful when clients or 3rd-parties make changes to the store.

If you don't think any changes have occured remotely, then feel free to skip this step and proceed to MMT, Git, & Template Branch Setup

Download & Commit Remote Assets¶

Create a new production sync branch from the main branch.
Terminal
```
git checkout main && git checkout -b production/YYYY-MM-DD
```
Delete all Miva template files
Terminal
```
rm -r miva-templates/*
```
Utilize mmt checkout to download all current production store Miva template files into your the production sync branch.
Terminal
```
mmt checkout REMOTE_CODE DIRECTORY

mmt checkout jsmith/production miva-templates
```

Commit the changes from your mmt checkout

You can git add . && git commit -m "production sync"

Or you can use the following snippet to separate whitespace changes, json changes, and template changes.

Terminal

git add -A && git diff --cached -w | git apply --cached -R && git commit -m "production sync of whitespace changes"
git add \*.json && git commit -m "production sync of json files"
git add -A && git commit -m "production sync of template changes"

Optionally, through FTP, download any additional source-files that might exist on the server outside the scope of Genesis. This might include a WordPress blog's PHP files or any other functionality you manage on the store.
- Just keep it to the files you know you will be editing or updating while working on your feature.
- There's no need to download the entire /htdocs/mm5/ directory. Use your best judgement. Less can be more here.
- You do not need to do this for build files located in the themes/genesis/public/ directory.
Optionally, commit the change from your FTP download of additional source files.
Terminal
```
git add . && git commit -m "production sync of additional source code"
```

Merge your Productions Sync Branch Into Main¶

Local RepoGitHub/BitBucket

Merge your production/YYYY-MM-DD branch into the main branch.
Terminal
```
git checkout main && git merge production/YYYY-MM-DD
```
Optionally, tag the merge with an appropriate release version number.
Terminal
```
git tag vX.X.X-production-sync.X
```

Push your branch up to Github/BitBucket and create a PR to merge your production/YYYY-MM-DD branch into the main branch.
1. If you created your branch remotely:
  Terminal
```
git push
```
2. If you created your branch locally:
  Terminal
```
git push -u origin HEAD
```
Optionally, tag the merge with an appropriate release version number, like vX.X.X-production-sync.X.
1. See how to create a tag in BitBucket
2. See how to create a Release on Github

Note

If you have any additional development or staging stores/domains, deploy all of the production sync changes to those stores keep them in sync with the production domain.

2. MMT, Git, & Template Branch Setup¶

The following process outlines the Git & MMT branching strategy to help you work on features in isolation away from the public's eyes.

We will be going through this example like we have been requested to update the Product Display Page (PROD), but the same concepts apply to just about any MMT, CSS, & JS update.

Create a prod-update Git branch from your main branch as a dedicated space to work on your changes
Terminal
```
git checkout main
git checkout -b prod-update
```
Create a dev Template Branch in Miva
- For our example we'll just use dev to keep things simple, but if you expect the potential for several developers or several features to be developed on a store at a time, then we would recommend creating a more personal jsmith branch or feature-specific branch like prod-update.
  Terminal
```
mmt branch create NEW_BRANCH_CODE --from SOURCE_BRANCH_CODE --store-code STORE_CODE --credential-key CREDENTIAL_KEY

mmt branch create dev --from production --store-code jsmith --credential-key jsmith
```

Create a Remote for MMT to push/pull Templates

Terminal

mmt remote add NEW_REMOTE_CODE --credential-key CREDENTIAL_KEY --branch-name BRANCH_CODE --store-code STORE_CODE

mmt remote add jsmith/dev --credential-key jsmith --branch-name dev --store-code jsmith

Checkout your branch's templates & commit any changes if they exist

Terminal

mmt checkout jsmith/dev miva-template
git add . && git commit -m "Ran mmt checkout jsmith/dev"

Create/update a Genesis Environment in themes/genesis/theme-settings.json

{
    "environments": {
        /* ...other environments here */
        "dev": {
            "moduleRoot": "mm5",
            "themePath": "themes/genesis/branches/dev/",
            "proxyUrl": "https://jsmith.mivamerchantdev.com/?BranchKey=9acbc94740ad3459804bea60c7ba444e"
        }
    }
}

Add Your BranchKey to your theme-settings.json > proxyUrl
1. To get your BranchKey:
  - Open miva-templates/.mmt/config.json and copy the value of the "branch_key" property.
  - Run the mmt info command and copy the Branch > Key: value
Build your CSS & JS for the dev Branch
Terminal
```
cd themes/genesis
pnpm run build dev
```
FTP Upload the CSS & JS build to the store's server
1. Create the htdocs/mm5/themes/genesis/branches/dev/ directory on your store's server through FTP
2. Upload the entire contents of the themes/genesis/public/ directory to the server htdocs/mm5/themes/genesis/branches/dev/public/
Preview your template branch to confirm everything is running properly
1. Miva Admin > Click Branch name in Top Right > Select the "dev" branch > Click the eye-icon in the top right of the window.

3. Template Development¶

The example will walk through how to change the number of words shown by the Short Description plugin on the product page.

First, ensure you can see the Short Description by:
1. Ensuring the admin's `PROD > Product Display > Custom Fields" has the "Short Description" custom field in set to load by default.
2. Adding a couple paragraphs of text to a product
3. Navigate to that product page and ensure you can see the Short Description copy above the "Add to Cart" button.
Open miva-templates/prod-product_display.mvt
Change l.settings:product:short_desc:max_word_count to 30
mmt push --notes "Changed short_desc:max_word_count to 30"
Reload the product page and you should now see more of the Short Description for a product.

4. Local CSS & JavaScript Development¶

Start your local development environment
Terminal
```
cd themes/genesis
pnpm run start dev
```

Wait for the previous command to complete and open the Local url it provides (ex. https://localhost:3000) in your browser of choice.

webpack 5.70.0 compiled successfully in 6431 ms
[Browsersync] Proxying: https://jsmith.mivamerchantdev.com
[Browsersync] Access URLs:
----------------------------------------
    Local: https://localhost:3000
    External: https://192.168.86.250:3000
----------------------------------------
    UI: http://localhost:3001
    UI External: http://localhost:3001
----------------------------------------
[Browsersync] Watching files...

Navigate to an example product that has a discount.
Customize your JavaScript
1. Open genesis/src/pages/PROD/PROD.js
2. Find the accordionMode inside initTabs and set accordionMode to 0
3. Save your file and the product page you were looking at on localhost:3000 should have reloaded.
4. Now when you view the PROD > Tabs on a mobile screen size, it should remain as Tabs instead of displaying as an Accordion.
Customize Your CSS
1. Change the Color of price discounts to be green
  1. Open themes/genesis/src/scss/config/_variables.scss
  2. Change $sale-price-color to a green color; like #008000;
  3. Save your file and the page you were looking at on localhost:3000 should have reloaded.
  4. Look for a product's discount price and it should now be green.
2. Increase the size of the product's name:
  1. Open themes/genesis/src/pages/PROD/PROD.scss
  2. Find .g-product-layout-details__name and change @include type-title-3; to @include type-title-2;
  3. Save your file and the page you were looking at on localhost:3000 should have reloaded.

5. Upload CSS & JavaScript Changes¶

So far we have only modified the CSS & JS locally. If someone else were to view the store on the template branch, they would only see the mmt push'd templates. To share the CSS & JS changes, we just need to build and upload the CSS & JS

Build your CSS & JS for the dev Branch
Terminal
```
cd themes/genesis
pnpm run build dev
```
FTP Upload the CSS & JS build to the store's server
1. Create the htdocs/mm5/themes/genesis/branches/dev/ directory on your store's server through FTP
2. Upload the entire contents of the themes/genesis/public/ directory to the server htdocs/mm5/themes/genesis/branches/dev/public/

6. Make Primary Branch¶

At this point we should have a running dev Template Branch with all of MMT, CSS, & JS the features you'd like you customers to have.

To make this branch public:
1. Miva Admin > User Interfaces
2. Click on branch name in top left
3. Click on Manage Branches
4. Check the box of the row for the branch you would like to launch (ex. "dev")
5. Click the "..." button
6. Click the "Make Primary Branch" link
7. Click the "Continue" button

Note

An improved workflow that does not require branch rotation is coming soon