Development and release workflow¶
This document describes the branch model, the pull-request flow, and the
release model for BigRAE. It is the reference cited by CONTRIBUTING.md,
CHANGELOG.md, and .gc/plan-rules.md.
Branch model¶
devis the integration branch. All feature and fix work targetsdev.mainis the stable release line. It receives onlydevtomainpromotion PRs and the release-please release PR; it never receives feature PRs or automated dependency bumps directly.
Pull-request flow¶
- Branch off
dev. - Give the PR a Conventional Commit title (
<type>(<optional-scope>): <subject>with a lowercase subject). Thepr-title-lintworkflow enforces the shape on every PR that targetsdev. - Squash-merge the PR into
dev. The squash makes the validated PR title the single commit subject that release-please reads once the change reachesmain, so the title, not the individual work-in-progress commits, is the release signal.
Do not hand-edit CHANGELOG.md and do not add changelog fragments. release-please
owns both the changelog and the version (see below).
Promoting dev to main¶
Open the promotion PR with make devmain. The target runs one gh pr create
against the clone's gh default repository (gh repo set-default --view). It
uses dev as the head branch, main as the base, a Conventional Commit title,
and a body that restates the merge strategy. It passes the repository
explicitly because a clone can have an upstream remote. Then an unpinned
gh pr create resolves the base repository to the fork parent and opens the
promotion PR against the upstream project. When no default is set, the target
stops. Run gh repo set-default <owner>/<repo> once in the clone, or set
DEVMAIN_REPO=<owner>/<repo>.
Merge the promotion PR with a merge commit. Never squash it. A squash collapses
every Conventional Commit subject in the promotion into one, so release-please
reads a single subject on main instead of the individual feature titles, and
the release PR loses the correct version bump along with the changelog entries
for that release.
pr-title-lint runs on the promotion PR, because Lint PR title is a required
status check on main as well as on dev. The title make devmain sends
satisfies it. The lint is not a release signal here, since the promotion
preserves the feature commits rather than collapsing them into one: it runs so
that the required context reports, which a workflow scoped away from main
cannot do.
No check constrains how the promotion PR is merged. The target carries the title; the maintainer carries the merge method.
Release model¶
Releases are coordinated by release-please
on main, configured by release-please-config.json and
.release-please-manifest.json at the repository root (ADR-042). BigRAE uses a
single umbrella version: one root package (release-type: simple), one
vX.Y.Z tag, and one CHANGELOG.md. The root version.txt is the committed
mirror of the current version; it is repository metadata, not an application
runtime setting. The component pyproject.toml, package.json, and
Chart.yaml versions keep their own meanings and are not swept into the
umbrella bump.
On each push to main, release-please maintains a release PR
(chore(main): release X.Y.Z) that bumps version.txt and prepends a new
CHANGELOG.md section generated from the Conventional Commit history since the
last release. Merging that release PR creates the vX.Y.Z tag and the GitHub
Release, and the sync-dev job opens a main to dev back-merge PR so dev
picks up the version bump and changelog. That back-merge PR is merged by a
maintainer; automation never force-updates main or dev.
What bumps the version¶
Commit subject on main |
Effect |
|---|---|
feat: |
minor bump |
fix: or perf: |
patch bump |
feat!:, fix!:, or a BREAKING CHANGE: footer |
major bump |
docs, chore, refactor, test, ci, build, revert |
no bump |
retained Keep-a-Changelog types (security, added, changed, deprecated, removed, fixed) |
no bump |
The retained Keep-a-Changelog types are accepted as valid PR titles for
continuity, but they do not cut a release. Use feat, fix, or perf, or a
breaking marker, when a change should produce a new version.
What a release is, and is not¶
A release is a source and provenance coordinate: a vX.Y.Z tag plus a GitHub
Release bound to one main commit. It is not a deployment, a package
publication, or a container-image coordinate. Deployment identity remains the
exact source revision and the verified OCI image digest (ADR-037); a SemVer tag
is never a deploy trigger or an image selector.
The release tag and GitHub Release are created by the release-please action
using the workflow's ephemeral GITHUB_TOKEN, mirroring the sibling RAES
repositories. The release PR is opened by that token, so branch-protection
required checks do not run on it automatically; a maintainer merges it (admin).
Towncrier to release-please transition (#1776)¶
Before this cutover, the changelog was managed with towncrier fragments under
changelog.d/. The transition consumed every pending fragment into a final
## [3.103.0] changelog section (preserving all content), then removed
towncrier.toml, changelog.d/, its template, and the CHANGELOG.md merge=union
attribute. release-please is now the sole changelog writer.
One-time activation runbook (maintainer, on main)¶
The dev-side cutover (config, workflow, final changelog, tooling reconciliation)
lands through the normal dev PR. Activating release-please then requires two
maintainer actions on main, because main is protected:
- Promote
devtomainthrough the usualdevtomainPR, preserving the feature commits. - On
main, create the baseline tagv3.103.0at the promotion commit and a matching GitHub Release..release-please-manifest.jsonalready records3.103.0, so release-please treats this as the last released version and scans only commits after it.
From the next push to main onward, release-please opens the release PR for
3.104.0 and later automatically; no further manual tagging is required for
routine releases.