Daily Workflow & Releasing
Nimara uses trunk-based development. main is the only long-lived branch, the source of releases,
and the Vercel production branch. Every commit on main must be safe to release.
Daily development
Start each change from the latest main:
git switch main
git pull --ff-only origin main
git switch -c feat/my-new-feature
Keep the branch focused on one releasable change and aim to merge it within two working days. Several pull requests can serve one issue or story. Do not use a shared feature branch as an integration branch.
For work that cannot be completed in that window:
- Split it into backward-compatible slices.
- Hide incomplete behavior behind a short-lived, default-off feature flag.
- Use branch by abstraction for a longer replacement or migration.
- Give every flag an owner and removal condition, and test each meaningful state.
Pull requests
Open every pull request against main and use a Conventional Commit title. Nimara squash-merges
pull requests, so this title becomes the commit semantic-release evaluates.
Before merging:
- Obtain the required approval and resolve review conversations.
- Pass
Linters & Testsand the four Vercel project statuses:Vercel – nimara-docs,Vercel – nimara-ecommerce,Vercel – nimara-ecommerce-stripe, andVercel – nimara-marketplace. - Bring the branch up to date with
main. - Complete risk-appropriate testing against the preview deployment.
GitHub squash-merges the change and deletes the branch. Direct pushes to main have no bypass.
During an active incident, only a member of the GitHub Admins team may use the ruleset's
pull-request-only bypass. Keep the change in a PR, use a squash merge, and record the actor, reason,
exact SHA, skipped requirements, and recovery owner in the incident record.
Additional QA
Vercel preview deployments replace branch-based development environments. For high-risk changes,
use the QA Deploy workflow to deploy the exact commit SHA to qa-1 or qa-2, then record that
SHA with the test evidence.
The workflow defaults to main for convenience and always reports the resolved deployed SHA. The
QA environment is an additional validation surface, not a release branch or a place to accumulate
changes.
Releasing
After a main push passes the full CI workflow:
- The Release workflow checks out that exact successful commit and runs semantic-release.
- Semantic-release determines whether the Conventional Commit history requires a version, tag, and GitHub release.
- Vercel independently builds each affected application from
mainand updates its production domain after a successful build. - Documentation is published from the same commit after the Release workflow succeeds.
There is no release branch and no later promotion merge. A main commit that does not require a new
semantic version can still deploy.
Production recovery
For an application regression:
- Restore or promote the previous known-good Vercel deployment.
- Open a revert or fix-forward pull request against
main. - Run the normal required checks and release a new immutable version when applicable.
Never force-push main, move a published tag, or treat a deployment rollback as a rollback of
database migrations, Saleor changes, Stripe actions, provider data, or environment changes. Those
stateful changes require their own approved compensating procedure.