Skip to content

Feature Branch Workflow#

A Feature Branch Workflow is a structured development approach that enables developers to work on new features, updates, or fixes in an isolated environment before merging changes into the main production branch. In Miva Merchant development, this workflow can be effectively managed using:

  • Miva Merchant Template Branching – Miva’s built-in system for managing template changes in a controlled environment.
  • MMT (Miva Merchant Tools) – A command-line tool that facilitates exporting, importing, and version-controlling templates.
  • Version Control Repositories (e.g., Git, Bitbucket, GitHub, GitLab) – Used to track template changes, collaborate with other developers, and maintain historical records of modifications.

Why Feature Branch Workflow?#

Benefits:#

  1. Isolated Development – Work on new features or fixes without affecting the live store.
  2. Safe Testing – Experiment with template changes in a separate branch before merging.
  3. Version Control – Maintain a history of template modifications with Git or another repository.
  4. Team Collaboration – Multiple developers can work on different features simultaneously without conflicts.
  5. Easy Rollbacks – Revert changes if needed without impacting the production environment.

Feature Branch Workflow Overview#

  1. Create a New Template Branch in Miva

    • Start a new branch in Miva Merchant Template Branching for the feature.

  2. Checkout Templates with MMT

    • Use MMT to pull templates from the Miva environment into a local development directory.

  3. Commit Changes to a Git Repository

    • Use Git to track and manage changes in a version-controlled environment.

  4. Develop and Test in the Branch

    • Implement changes in Miva’s branch while maintaining a linked repository.

  5. Merge and Deploy the Feature

    • Once tested and approved, merge the feature branch into the main branch and push it live.

Step-by-Step Guide#

Create a New Template Branch in Miva#

Miva’s Template Branching System allows you to create an isolated environment where you can make template modifications without affecting the live store.

Steps:#

  1. Navigate to User Interface > Template Branches.
  2. Click Create Branch.
  3. Copy from the Primary branch and name the branch descriptively (e.g., feature-new-header).
  4. Ensure that you are working in the new branch before making any changes.

Checkout Templates Using MMT#

MMT (Miva Merchant Tools) allows you to sync templates between the Miva admin and a local development environment.

Install MMT (If Not Already Installed)#

pip3 install --user miva-mmt

More information about installing MMT can be found in the Getting Started docs.

Add a Credential for Miva Authentication#

mmt credential add --url URL [--http-basic-auth-username HTTP_BASIC_AUTH_USERNAME] [--http-basic-auth-password HTTP_BASIC_AUTH_PASSWORD] [--token TOKEN] [--signing-key SIGNING_KEY] [--ssh-username SSH_USERNAME] [--ssh-private-key SSH_PRIVATE_KEY] key
You will be prompted to enter:

  • Key: A unique identifier (e.g., miva-dev).
  • Store URL: The URL to the Miva store JSON URL (e.g., https://yourstore.com/mm5/josn.mvc).
  • Credentials:
    • SSH Username & Key: Miva Merchant username associated with the SSH credential & filepath to the SSH private key
    • Token & Signing Key: The API token and API signing key used to make API requests

Verify credentials with: 

mmt credential list

Add a Remote for the Store#

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

Example: 

mmt remote add --credential-key miva-dev --branch-name feature-new-header --store-code TEST feature-new-header

Verify the remote: 

mmt remote list

Checkout the Template Code from the Feature Branch#

mmt checkout remote-key [path]

Example: 

mmt checkout feature-new-header ./

This command will:

  • Download the latest template files from the feature-new-header branch.
  • Create a local working directory with all relevant templates.
  • Sync files locally so they can be edited in a text editor.

Commit and Push Changes to a Git Repository#

Using a repository ensures version control and collaboration with other developers.

Initialize a Git Repository (If Not Already Done)#

git init
git remote add origin https://github.com/your-repo/miva-theme.git

Commit Changes#

git add .
git commit -m "Updated header template in feature-new-header branch"

Push to Remote Repository#

git push origin feature-new-header
This keeps your changes versioned and allows collaboration or rollbacks if needed.

Develop and Test in the Branch#

Work on your changes within the Miva branch and commit updates to your repository.

Edit Templates in Miva Admin#

  1. Navigate to User Interface > Pages.
  2. Select the template you want to edit.
  3. Apply modifications and save changes.

Pull Latest Changes from Git (If Working in a Team)#

git pull origin feature-new-header
This ensures that your local environment remains in sync with the repository.

Test Changes in Miva#

  • Use Preview Mode to see how the feature looks before merging.
  • If working with a team, create a test link and share it for review.

Merge and Deploy the Feature#

Once development and testing are complete, the feature needs to be merged into the main branch.

Merge the Miva Template Branch#

  1. Go to User Interface > Template Branches.
  2. Select Merge and choose the target branch (e.g., main or production).
  3. Review the changes and confirm the merge.

Merge the Git Branch#

git checkout main
git merge feature-new-header
git push origin main
This finalizes the feature integration and ensures the repository reflects the latest updates.

Best Practices#

Name Branches Clearly#

  • Use descriptive names that explain the purpose of the branch: 
    feature-new-header
bugfix-cart-layout
update-footer-links

Keep Commits Small and Descriptive#

  • Example commit messages: 
    git commit -m "Updated header design with new logo placement"
git commit -m "Fixed responsive layout issue on product grid"

Sync Regularly#

  • Pull the latest changes from both Git and Miva to avoid conflicts.
  • Example: 
    git pull origin feature-new-header
mmt pull

Test in a Staging Environment#

  • Before merging to the main branch, test changes thoroughly in a branch or test store.

Use Branch Protections in Git#

  • Require approvals before merging to main.
  • Enable branch protections to prevent accidental overwrites.

Summary#

Integrating Miva Template Branching, MMT, and Git into a Feature Branch Workflow allows developers to safely build, test, and deploy changes without affecting the live store. This workflow ensures organized development, prevents conflicts, and streamlines collaboration.