Releasing a change

A storefront release is a merge to main in asc-shopify-theme. Shopify deploys that branch to the connected theme. A merge in asc-shopify-src has no effect on the storefront by itself, because its output lives in the theme repository.

1. Start from current branches

Staff edits in the theme editor reach theme main as shopify[bot] commits at any time. Pull before you branch.

git checkout main && git pull
git -C theme checkout main && git -C theme pull

2. Name the branches

Create a branch with the same name pattern in each repository you change:

<issue number>-asc-<job number>-<type>-au-<short description>

For example 92-asc-071-fx-au-image-gallery-scrolling. The issue number is the GitHub issue in that repository, so the same job often has different numbers in the two repositories, for example 95-asc-073-… in asc-shopify-src and 96-asc-073-… in the theme.

git checkout -b 95-asc-073-fx-au-example
git -C theme checkout -b 96-asc-073-fx-au-example

3. Build

Run npm run dev while you work, or npm run build once before committing. Both write into theme/assets/.

4. Commit in the theme repository

Commit Liquid, JSON and the rebuilt files together.

git -C theme status
git -C theme add sections/ snippets/ templates/ assets/
git -C theme commit

Rebuilt files usually include assets/*.bundle.js, assets/*.bundle.js.LICENSE.txt, assets/styles.css and assets/vendors.css.

5. Commit in asc-shopify-src

git add src/
git commit

The husky pre-commit hook runs:

npm run format
git add -u
npm run build
git add -u

It formats the whole repository, including theme/, and rebuilds the bundles. git add -u in asc-shopify-src cannot stage files inside the submodule. After committing here, run git -C theme status and commit any files the hook changed in the theme.

The hook takes some time because it runs a production build. HUSKY=0 git commit skips it, but then you must run npm run build and commit the output yourself.

.gitmodules sets ignore = all, so the submodule pointer is not shown as changed and is not updated routinely. To record which theme commit a source change was built with, stage it explicitly:

git add theme

6. Preview

Push the theme branch and connect it to an unpublished theme in Shopify Admin under Online Store, Themes, Add theme, Connect from GitHub. Earlier feature branches were previewed this way, which is why bot commits named asc-shopify-theme/<branch> appear in history.

Alternatively, npm run theme-dev -w @repo/theme serves your working copy as a development theme.

Share the preview link for review. Check the pages listed in Testing.

7. Merge theme main into your branch

Immediately before merging, bring your theme branch up to date:

git -C theme fetch
git -C theme merge origin/main

Conflicts usually appear in templates/*.json, sections/header-group.json, sections/footer-group.json and config/settings_data.json, because those are the files the theme editor writes. Keep the version from main unless your change deliberately alters that setting. Discarding a bot commit's change discards a staff member's edit on the live site.

If the merge brought in bot commits that changed Liquid files, re-run the build and check the preview again.

8. Merge

1. Open a pull request into main in each repository. There is no branch protection, but pushing straight to main bypasses review.
2. The theme repository runs an AI review action on pull requests. Treat its comments as suggestions.
3. Merge the theme pull request. This deploys.
4. Merge the asc-shopify-src pull request at the same time, so src/ on main matches what is live.

After the asc-shopify-src merge, the "Merge main to staging" action updates staging. The action then reports a failure because the dev-content branch it also targets does not exist. The staging merge itself has succeeded.

9. Confirm the release

1. Open the live site in a private window and check the changed pages.
2. In the browser's network panel, confirm the changed bundle has a new ?v= value in its URL.
3. If the storefront has not changed, check the connected theme's GitHub status in Shopify Admin under Online Store, Themes.

Roll back

Revert the merge commit on theme main and push. Shopify redeploys the reverted files. Revert the matching asc-shopify-src merge as well. Detail is in Deploy and roll back.

Changes outside this repository