CONTRIBUTING.md: document single-trunk + RC-tag release model
This commit is contained in:
parent
3caad809a3
commit
4f0fe2571d
1 changed files with 45 additions and 41 deletions
|
|
@ -7,16 +7,10 @@ workflow described here.
|
|||
|
||||
## Branches
|
||||
|
||||
- **`main`** — release branch, always tag-ready. Nothing is committed to it
|
||||
directly; it only moves forward via a `beta` merge (see below).
|
||||
- **`dev`** — integration branch. All day-to-day work lands here first.
|
||||
Every push to `dev` automatically builds and publishes a **dev-track**
|
||||
build (see Tracks below) — use this to test your change in a real install
|
||||
before it goes any further.
|
||||
- **`beta`** — a frozen stabilization branch, cut from `dev` periodically.
|
||||
Every push to `beta` automatically builds and publishes a **beta-track**
|
||||
build. While a freeze is active, only fixes for issues found *in that
|
||||
freeze* should land on `beta`.
|
||||
There is one long-lived branch: **`main`**. All day-to-day work lands here.
|
||||
Every push to `main` automatically builds and publishes a **dev-track**
|
||||
build for both products (see Tracks below) — use this to test your change
|
||||
in a real install before cutting anything more formal.
|
||||
|
||||
New work — features and bug fixes alike — goes on a short-lived branch:
|
||||
|
||||
|
|
@ -25,28 +19,35 @@ feature/<short-name>
|
|||
fix/<issue-number-or-short-name>
|
||||
```
|
||||
|
||||
Branch off `dev`, open a PR/push back into `dev` when ready. If you're fixing
|
||||
something reported against an active `beta` freeze, branch off `beta`
|
||||
instead, merge the fix there to unblock testers, and also forward the same
|
||||
fix into `dev` so it doesn't quietly reappear next cycle.
|
||||
Branch off `main`, open a PR/push back into `main` when ready. Short-lived
|
||||
branches get deleted on merge — they never accumulate the kind of drift a
|
||||
second long-lived branch does.
|
||||
|
||||
## The release cycle
|
||||
|
||||
1. Work accumulates on `dev` via `feature/x` / `fix/x` branches. Each push
|
||||
auto-publishes a dev build — install it with `bakery track set dev` and
|
||||
`bakery update --all`, then report or fix anything broken with another
|
||||
push to `dev`.
|
||||
2. Once `dev` has gone roughly **a week** without new issues, `beta` is cut
|
||||
fresh from `dev`'s current tip. This freezes it as the stabilization
|
||||
target — `dev` keeps moving independently starting the next cycle.
|
||||
3. `beta` is open for anyone to test: `bakery track set beta` and
|
||||
`bakery update --all`. **File issues against anything you find on this
|
||||
repo's Forgejo issue tracker.** Fixes land via `fix/<issue>` branches
|
||||
merged into `beta`.
|
||||
4. Once `beta` has gone roughly **a month** without new issues, it's merged
|
||||
into `main` and tagged `vX.Y.Z` — that tag is what actually triggers the
|
||||
stable release build. `beta` is then reset from `dev` to start the next
|
||||
cycle.
|
||||
There's no separate `beta` or release branch — "stable" and "beta" are both
|
||||
just **tags** on `main`, not branches that need to be kept in sync:
|
||||
|
||||
1. Work accumulates on `main` via `feature/x` / `fix/x` branches. Each push
|
||||
auto-publishes a dev build for both `bakery` and `bread-theme` — install
|
||||
with `bakery track set dev` and `bakery update --all`, then fix anything
|
||||
broken with another push.
|
||||
2. When you want to stabilize before a real release, tag a release
|
||||
candidate: `git tag vX.Y.Z-rc.1 && git push origin vX.Y.Z-rc.1` (push to
|
||||
both remotes). That tag alone triggers a beta-track build —
|
||||
"freezing" is just pausing pushes to `main` while you test it, not a
|
||||
branch operation. Cut `-rc.2`, `-rc.3`, etc. for further fixes.
|
||||
3. Once an RC has gone without issues, tag the real release:
|
||||
`git tag vX.Y.Z && git push origin vX.Y.Z` — that's what triggers the
|
||||
signed stable release build.
|
||||
|
||||
**Note**: `bakery` and `bread-theme` share the same `v*` tag pattern
|
||||
(both `release-bakery.yml` and `release-bread-theme.yml` trigger on
|
||||
`tags: ['v*']`, pre-existing behavior this doc isn't changing) — a single
|
||||
tag push builds and publishes a release for *both* products at once. If
|
||||
you ever need to release one independently of the other, that's a real gap
|
||||
worth fixing in the workflow files themselves, not something to work around
|
||||
by hand.
|
||||
|
||||
## Tracks, from a user's perspective
|
||||
|
||||
|
|
@ -58,14 +59,15 @@ bakery update --all # pull the latest build on your current track
|
|||
|
||||
| Track | What it is | Published from |
|
||||
|--------|-----------|-----------------|
|
||||
| `stable` | The last tagged release | `main`, on a `vX.Y.Z` tag push |
|
||||
| `beta` | Current stabilization freeze | `beta`, on every push |
|
||||
| `dev` | Bleeding edge | `dev`, on every push |
|
||||
| `stable` | The last tagged release | a `vX.Y.Z` tag |
|
||||
| `beta` | Latest release candidate | a `vX.Y.Z-rc.N` tag |
|
||||
| `dev` | Bleeding edge | `main`, on every push |
|
||||
|
||||
Dev/beta versions are auto-computed (`X.Y.Z-dev.<timestamp>+<sha>` /
|
||||
`-beta.…`) from the latest published stable tag, so they always sort as
|
||||
newer than what you have installed — no manual version bumping needed when
|
||||
pushing to `dev` or `beta`.
|
||||
Dev versions are auto-computed (`X.Y.Z-dev.<timestamp>+<sha>`) from the
|
||||
latest published stable tag, so they always sort as newer than what you
|
||||
have installed — no manual version bumping needed. Beta versions are just
|
||||
the RC tag itself (already valid semver, already sorts below the real
|
||||
release it's a candidate for).
|
||||
|
||||
## Local development
|
||||
|
||||
|
|
@ -79,11 +81,13 @@ Run the same commands with `-p bread-theme --bin bread-theme` for that crate.
|
|||
|
||||
## CI
|
||||
|
||||
- `dev-bakery.yml` / `dev-bread-theme.yml` — triggered on push to `dev`.
|
||||
- `beta-bakery.yml` / `beta-bread-theme.yml` — triggered on push to `beta`.
|
||||
- `release-bakery.yml` / `release-bread-theme.yml` — triggered on a `v*` tag
|
||||
push, cuts the actual stable release.
|
||||
- `package.yml` — publishes to the `[breadway]` pacman repo, also tag-triggered.
|
||||
- `dev-bakery.yml` / `dev-bread-theme.yml` — triggered on push to `main`.
|
||||
- `rc-bakery.yml` / `rc-bread-theme.yml` — triggered on any `vX.Y.Z-rc.N`
|
||||
tag push.
|
||||
- `release-bakery.yml` / `release-bread-theme.yml` — triggered on any other
|
||||
`v*` tag push, cuts the actual stable release.
|
||||
- `package.yml` — publishes `bakery` to the `[breadway]` pacman repo, also
|
||||
tag-triggered.
|
||||
|
||||
All CI runs on a self-hosted runner; nothing runs automatically on plain
|
||||
commits or PRs beyond the track builds above. See
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue