Skip to content

RELEASES.md

Latest commit

 

History

History
36 lines (26 loc) · 2.65 KB

RELEASES.md

File metadata and controls

36 lines (26 loc) · 2.65 KB

Releases

Branch structure and intent

  • main always mirrors the latest code that has actually shipped. Every public release commit lives on main and is tagged there.
  • For each major series we keep a long-lived N.x branch (for example 0.x, 1.x, 2.x, …). That branch collects all work that will eventually be released as N.y.z.
  • A series branch covers the entirety of that major train: 0.x carries everything from 0.1 through 0.1.0, 0.2.3, etc.; when we move on to 1.0 we repeat the pattern with 1.x, and so on.
  • There is no separate release branch. The matching N.x branch is the staging ground; once it is ready we merge it to main and cut the tag.

Day-to-day development workflow

  1. Identify the active series branch (e.g., 0.x). That branch always tracks the next unreleased work.
  2. Create short-lived feature branches from that series branch: git switch -c feature/xyz 0.x.
  3. Land pull requests back into the same series branch (0.x). Keep it green: rebase frequently, run the full test suite, and update documentation there.
  4. main stays untouched during the iteration and continues to point at the previously shipped tag.

Cutting a release from a series branch

  1. Pick the exact semantic version you plan to ship (e.g., 0.3.0).
  2. Ensure the matching series branch (e.g., 0.x) already contains every change you want plus any release-specific metadata (CHANGELOG entries, config tweaks, etc.).
  3. Merge the series branch into main (fast-forward if possible): git switch main && git merge --ff-only 0.x.
  4. Tag the resulting commit on main using the v<major>.<minor>.<patch> format: git tag v0.3.0 && git push origin main v0.3.0.
  5. Deploy from main so production always matches the latest tag.

Moving to the next train

  • After tagging (say v0.3.0), decide whether you need to keep the old series alive for hotfixes. If so, leave the 0.x branch in place for those fixes; otherwise it can be closed.
  • Start the next cycle by creating the new series branch from main: git switch -c 1.x main. From that point onward, all feature work for 1.0 through 1.0.0 lands on 1.x until it is merged back into main and tagged.
  • At any given time main must track whichever series branch represents the most recent release so that the code on main and the highest tag are always in sync.

Quick reference

  • Feature work → feature/* branches cut from the active N.x series branch.
  • Integration/testing → happens directly on the series branch (N.x).
  • Release → merge N.x to main, then tag vN.y.z on main.
  • Latest code in production → always the HEAD of main and the highest vN.y.z tag.