Release Contract & Branching Template

Document version v2026100501 (quote this version when discussing or citing) · 中文版. For every development department, whatever the stack and wherever it is deployed. The document has two layers: Part A, the delivery contract, is what every team hands to SRE and is mandatory; Part B, the branching template, is a recommended way to run version control inside a repo, which teams may adopt, adapt or ignore. Each section is marked contract or template. Implementation details are in CI/CD Details.

1. At a glance

flowchart LR
  T["Teams' MRs
merged before tagging"] --> RM["Release Manager
one per repo"]
  RM -->|"D-1: tag + commit hash
+ release plan"| S["SRE"]
  S -->|"release day"| G["gray
real traffic"]
  G -->|"problem in any repo:
withdraw all · re-deliver
gray again until 14:00"| RM
  G -->|"whole set passed
same tags"| P[("production")]
  classDef long fill:#111a2c,stroke:#3fd0e8,color:#f0f4fc,stroke-width:2px
  classDef short fill:#111a2c,stroke:#3a4763,color:#d7deed
  classDef gate fill:#241d0f,stroke:#e8c56a,color:#f0d9a0
  class RM,S long
  class T short
  class G gate

2. Roles contract

3. The delivery contract contract

1. Release ManagerEach release of a repo has exactly one Release Manager, regardless of how many teams or departments have changes in it. The Release Manager integrates all MRs and release details for that repo and is SRE's only contact; SRE takes deployment requests only from them. When a release spans several repos, their Release Managers agree one release plan (repos, order, version to revert to) and hand it to SRE together.
2. DeadlineTag + full commit hash + release plan reach SRE by the end of the working day before release day. Anything later moves to the next release day.
3. One deploymentOne repo, one release day, one tag. All MRs are merged before the tag is created; SRE never waits for merges.
4. Release dayGray (real traffic) runs in a fixed window: from 11:00 to 14:00 on release day. Within the window SRE may run gray any number of times; each round takes the whole set. If gray shows a problem in any repo, SRE withdraws the whole day's release from gray (every repo in the release plan). After all Release Managers have confirmed, they deliver tag + commit hash again for every repo, changed or not, and the whole set goes through gray again from the start. Gray ends at 14:00: a round still running at 14:00 is stopped and withdrawn, and the whole release moves to the next release day. Only a set that has passed gray by 14:00 goes on; SRE then deploys the same tags and the same artifacts to production in release-plan order (the production deploy itself may run after 14:00).
5. Tag ↔ hashBefore deploying, SRE checks that each tag resolves to the delivered commit hash. A mismatch is not deployed until the Release Manager confirms a corrected pair.
6. RevertibilityEvery release is either revertible (the previous version can be redeployed; DB migrations are backward compatible) or its change sits behind a toggle that can be switched off. The Release Manager states which in the request. If neither holds, SRE still deploys; on a problem, the development team fixes forward. That is the development team's responsibility.
7. RollbackSRE rolls back by redeploying each repo's previous version in reverse release-plan order, the whole release at once, or by switching the toggle off. Whether to release again the same day (for example with the problem feature taken out) is the Release Managers' decision; a same-day re-release is re-delivered as a whole set and must pass gray by 14:00, otherwise it goes to the next release day.
8. HotfixOnly the three criteria in section 5. The Release Manager requests it with evidence; SRE confirms. Delivered the same way (tag + hash), gray then production, outside release day.
9. BoundaryVersion-control mistakes inside a repo (a tag on the wrong commit, branches started from the wrong point, merge mistakes) are the development team's to fix. SRE deploys what was delivered.

4. Release day contract

How often release day happens is up to the teams (weekly, every few days, daily). The timeline is always the same:

5. Hotfix contract

Only these three kinds of fix may be deployed outside release day; everything else waits for the next release day:

1. Fixes for incidents that produced customer complaints.
2. Fixes for problems affecting accounting or payment flows.
3. Fixes that improve system performance.

Requested by the Release Manager, confirmed by SRE: the request states which kind it is and attaches the evidence (complaint ticket number, accounting anomaly record, performance data). SRE accepts it only if it qualifies. A confirmed hotfix is delivered like any release (tag + full commit hash, revert method) and goes to gray, then production. How the fix is branched inside the repo is up to the team; section 9 shows one way.

6. Revertibility and rollback contract

A release that cannot be reverted and has no toggle cannot be undone by SRE. That is why every request states its revert method.

1. SREDecides with the Release Managers that a rollback is needed and announces it.
2. SREIn reverse release-plan order, redeploys each repo's previous version (as stated in the release plan). Every repo in the plan is rolled back.
3. Release ManagersDecide what ships again and when: the same day (re-delivered as a whole set, passing gray by 14:00) or a later release day.

7. The deployment request contract

The Release Manager opens one request per repo per release; SRE approves it and the platform deploys. Gray and production use the same request. It looks like this:

• After approval the platform delivers the version: containerised services are synced by GitOps, services on VMs by a deployment job. Development teams never need to touch this layer.
• Turning a feature toggle on or off is the same kind of request, marked config-only.
• Freeze periods (for example before a major sale) are set by SRE; requests can still be opened but are not approved.

8. Branches template

One way to run a repo that makes the contract easy to meet. Teams can use it as is, adapt it, or use their own.

9. A worked cycle template

1. DeveloperBranches feat/* from master, develops and verifies in a self-verification environment.
2. Release ManagerBefore D-1: agrees with the teams what ships, cuts release/X.Y.Z from master, and agrees the release plan with the other repos' Release Managers.
3. DeveloperOpens an MR from each shipping feat/* into release/X.Y.Z; it is merged after feature review.
4. Release ManagerCreates vX.Y.Z-rc.1 on release/X.Y.Z (the system builds the artifact) and delivers tag + commit hash on D-1.
5. SRERelease day: gray, then production (Part A). If gray fails, the fix is made on the original feat/*, merged into the release again, rc.2 is created, re-delivered and must pass gray by 14:00.
6. Release ManagerOnce every repo in the release plan is verified in production, merges release/X.Y.Z into master and creates the release tag vX.Y.Z (same content as the rc in production); the release and merged feat branches are deleted.

Removing a feature from the release

When one feature cannot ship but the others should: the teams agree which merges to revert on release/X.Y.Z (the feature and anything depending on it), revert them via MR, create a new rc and deliver it. The reverted feature stays on its feat/* branch for a later release. A feature behind a toggle can simply stay off.

Hotfix branching

flowchart LR
  M0["master"] --> H["hotfix/*"]
  H -->|"Case A: MR"| R["release/X.Y.Z
(in prod, not merged)"]
  R -->|"new rc · delivered"| G1["gray"] --> P1[("production")]
  P1 -.->|"merged with the release"| M1["master · vX.Y.Z"]
  H -->|"Case B: rc tag · delivered"| G2["gray"] --> P2[("production")]
  P2 -->|"verified · RM merges"| M2["master · vX.Y.(Z+1)"]
  classDef long fill:#111a2c,stroke:#3fd0e8,color:#f0f4fc,stroke-width:2px
  classDef short fill:#111a2c,stroke:#3a4763,color:#d7deed
  classDef gate fill:#241d0f,stroke:#e8c56a,color:#f0d9a0
  class M0,M1,M2 long
  class H,R short
  class G1,G2 gate

Optional: QC acceptance on an rc (future)

A team that wants functional acceptance before delivery can deploy the rc to its own test environment and have QC accept it before D-1. The tag QC accepted is then the one delivered, so production runs what QC tested. This is not part of today's flow.

10. Versions and artifacts template

11. Feature toggles template

A feature toggle is a setting read at runtime that decides whether a new feature's path is used. It is one of the two ways to meet the revertibility rule in section 6. One feature then ships in two deployments:

flowchart LR
  A["① Ship the code
toggle off by default
normal release"] --> B["② Turn the feature on
setting change only, same artifact
config-only request by the RM"]
  B --> C["③ Remove the toggle
normal release"]
  B -.->|"problem"| D["Turn it off again"]
  classDef s fill:#111a2c,stroke:#3a4763,color:#d7deed
  classDef g fill:#241d0f,stroke:#e8c56a,color:#f0d9a0
  class A,C,D s
  class B g

• Toggle values are managed in the same place as versions and deployed by SRE on a config-only request; not in a database, not in code.
• Every toggle has an owner and an expiry date; it is removed within 30 days of full rollout. Toggles wrap new features only, never bug fixes; database migrations must still be backward compatible.
• How each stack reads toggles and whether a change needs a restart: see CI/CD Details.

12. FAQ

Do we have to use the branching template?

No. Part A is the contract; Part B is one way to meet it. What SRE checks is the delivery: one Release Manager, one tag + commit hash per repo by D-1, a stated revert method.

What is the difference between the Release Manager and a Dev Lead?

The Release Manager is the repo's single contact towards SRE for one release: integrates every team's MRs and release details and delivers the tag + hash. Dev Leads still decide inside their teams what is ready. One person can be both.

Several departments change the same repo. Who is the Release Manager?

Still exactly one person for that repo's release; the departments agree who. SRE does not take separate requests per department for the same repo.

Why D-1, and why gray from 11:00 to 14:00?

D-1 gives SRE time to check tag ↔ hash and prepare the release plan; on release day SRE only deploys. The 11:00–14:00 window gives room for several gray rounds and still leaves the afternoon for production and for watching it after release.

Production had to be rolled back. Can we release again the same day?

That is the Release Managers' decision. For example, the problem feat is taken out and the rest released again; the whole set is re-delivered and must pass gray by 14:00. After 14:00, it goes to the next release day.

Only one repo failed in gray. Why withdraw everything?

Repos in one release depend on each other through the release plan. Withdrawing and re-running the whole set keeps gray and production consistent with one plan instead of a partial mix.

Our tag pointed at the wrong commit and others branched from it. Can SRE fix it?

No. Version control inside the repo belongs to the development team. Create a correct new tag and deliver it; SRE deploys the pair that was delivered.

My fix is not one of the three hotfix kinds, but it is urgent. What now?

Take the next release day. If it cannot wait, check whether a feature toggle can switch off the problem; SRE does not accept a hotfix that does not meet the three criteria.

Can I cherry-pick commits to another branch?

Not recommended. A feature usually has several commits plus later fixes, so it is easy to miss one, and cherry-picks create duplicate commits that later conflict. Merge whole branches through MRs; remove a feature with revert.

Can an MR use squash?

How does "build once" work with Next.js NEXT_PUBLIC_*?

At build time CI has no environment settings, so the image cannot contain values that differ per environment. Server-side code reads environment variables at runtime; browser-side values use same-origin relative paths or are provided by the server at runtime. See CI/CD Details.

13. References

Every rule maps to a mainstream industry practice; a discussion is about whether a practice fits us, not whose approach is better.

• GitLab Docs — GitLab Flow (release branches, upstream first), Protected branches, Merge request approvals, Code Owners, Releases
• semver.org — Semantic Versioning 2.0.0 (pre-release -rc.N)
• Humble & Farley, Continuous Delivery (2010) — build once, deploy many; artifact promotion
• Canary release / progressive delivery (gray release) — Danilo Sato, “CanaryRelease” (martinfowler.com, 2014)
• DORA / Accelerate (2018) — short-lived branches and delivery performance
• Pete Hodgson, “Feature Toggles” (martinfowler.com, 2017)
• OpenGitOps — GitOps Principles v1.0