Files

T

Paul Nothaft 3ca6378bd7 chore: workflows + RELEASING.md for the post-rename branch model

After the org move + branch rename (#669):
  beta  → main   (active development)
  main  → stable (curated release channel)

This PR rewires the workflows that referenced the old branch names so
release-please and the Docker build target the right channels.

## Workflow changes

### `.github/workflows/docker-build.yml`

- **Push triggers**: `[main, beta]` → `[main, stable]` (both `push.branches`
  and `pull_request.branches`). `beta` no longer exists; `stable` is the
  curated channel that should also produce builds.
- **`is_prerelease` detection**: pre-release context was decided by
  `refs/heads/beta`; now decided by `refs/heads/main` (active dev →
  prerelease, `-beta.N` version suffix unchanged).
- **`:latest` + `:stable` tagging**: were gated on `{{is_default_branch}}`
  (which used to be `main` = stable channel). Default branch is now `main`
  = active dev, so the implicit gate would have aliased `:latest` to dev.
  Both tags now explicitly gate on `refs/heads/stable` OR a non-prerelease
  release tag.
- **`:beta` tag**: REMOVED. Active-dev pulls are `:main` (auto-generated
  by `type=ref,event=branch`). The pre-rename `:beta` tag remains frozen
  at its last build under Option B / #669 — operators are expected to
  update to `:main` or pin to a versioned tag.

### `.github/workflows/release-please.yml`

- `branches: [main]` → `branches: [stable]`. This is the **stable**
  release-please workflow (uses `release-please-config.json`); after the
  rename, the stable channel lives on the `stable` branch.

### `.github/workflows/release-please-beta.yml`

- `branches: [beta]` → `branches: [main]`.
- `target-branch: beta` → `target-branch: main`.
- This is the **pre-release** release-please workflow (uses
  `release-please-config-beta.json`, `prerelease: true`); after the rename,
  pre-releases are cut from the new `main` (active dev). The version-suffix
  scheme stays `-beta.N` so existing operator pins keep working.

## RELEASING.md

Rewrote the TL;DR, "How a stable release is cut", and hotfix path to
reference the new branch names. Added a one-line "branch model background"
note pointing at #669 so future maintainers know why `main` means active
dev (the opposite of what some projects use). Filename conventions:
`release/X.Y.Z-merge-from-main` (was `…-from-beta`); promotion PR title
`promote main → stable as vX.Y.Z` (was `promote beta → main`).

## Why combined with PR A's content as a single PR

Originally planned as two PRs (B = workflow triggers, C = release-please
reconfigure). Splitting wasn't worth it: the configs are branch-agnostic
(`release-please-config.json` and `release-please-config-beta.json` don't
mention branch names internally), and not bundling them meant a window
where the stable release-please workflow would fire on pushes to the new
`main` (active dev) — exactly the wrong place. Single PR closes that gap.

## Versioning scheme — kept

No version-scheme decision needed. The `-beta.N` suffix on pre-release
versions is preserved (existing operator pins like `v3.71.3-beta.0` keep
working). If a `v4.0.0-pre.N`-style reset is desired later, that's a
separate PR with explicit operator-comms attached.

2026-06-29 22:15:31 +02:00

8.3 KiB

Raw Permalink Blame History

Release Process

This document describes how PicPeak releases are cut. It's the maintainer's reference, not user documentation — for the user-facing channel choice (stable vs pre-release) see the Release Channels section in README.md.

TL;DR

main branch receives all merged work (active development). Every push triggers a release-please PR that proposes the next vX.Y.Z-beta.N pre-release. Merging that PR tags the pre-release and publishes Docker images under the :main rolling tag + the version-specific tag.
stable branch holds the curated stable channel. Stable releases are cut from a known-good main point via a release/X.Y.Z-merge-from-main branch and a manual PR to stable. Merging that PR triggers release-please to propose the stable release.
Target cadence: a stable release every 4–6 weeks, or sooner if main has been quiet and ready for promotion.

Branch model background — main (active dev) was previously called beta, and stable (curated channel) was previously called main. The rename happened with #669 to match the convention every other open-source project uses. The mechanics below all reference the post-rename names.

Cadence target

4–6 weeks between stable releases is the working target. Reasoning:

Long enough that each stable carries meaningful changes worth the upgrade burden.
Short enough that pre-release users aren't carrying the "real" project alone for months — the stable channel should actually be usable as the recommended channel for new installs.
Aligns with how release-please surfaces pre-releases (multiple pre-release points usually accumulate inside a 4–6 week window, which gives natural promotion candidates).

This is a target, not a hard rule. Cut sooner if main has been quiet and stable longer than usual. Cut later if main is in flux for security or migration reasons.

Promotion criteria

A main tip is eligible for promotion to stable when all of the following hold:

CI green on the candidate main tip. Specifically: schema-drift (upgrade-from-bootstrap), fresh-install, Tests (backend Jest + frontend Vitest), the four Build and Push Docker Images arch matrices, and GitGuardian Security Checks.
No open bug-labelled issues against the candidate for at least 7 days. Issues fixed-but-not-yet-closed count as fixed; verify their PR is in the candidate main tip before closing them out.
An upgrade walk has been done on real production-shaped data — apply the candidate's migration chain to a snapshot of the previous stable's DB and verify no manual intervention is required. CI proves fresh-install works; the upgrade walk is what proves the upgrade path works.
Operator-time smoke on the candidate: log in, create event, upload photos, share gallery, open as a customer, log out. Catches binary-incompatibility regressions and UI-level breaks that unit tests don't see.

If any of the four fail, the promotion waits. File any blockers as bug-labelled issues and let them bake on main before re-evaluating.

How a stable release is cut

The actual mechanics, in order:

Pick the main tip. Confirm it satisfies the four promotion criteria above. Note the exact SHA — that's what you're promoting.
Create the release branch from the main tip.
```
git push origin <main-tip-sha>:refs/heads/release/X.Y.Z-merge-from-main
```
Naming convention: release/X.Y.Z-merge-from-main, where X.Y.Z is the stable version you intend to land. release-please will write the actual X.Y.Z on merge — the branch name is just a human label.
Open a PR to stable. Title: chore(release): promote main → stable as vX.Y.Z. Body should summarise the major themes since the previous stable, the migration count, and any operator notes (e.g. "this release adds 22 migrations; existing installs should snapshot before upgrading"). See PR #568 as a worked example (predates the rename; the mechanics are unchanged).
Resolve conflicts. stable almost always has commits main doesn't (security backports, release-please's stable-channel release commits, README rewrites). For each conflicting file, decide deliberately:
- backend/package.json / package-lock.json + frontend/package.json / package-lock.json — usually take main's version (superset), but verify any security-pinned deps (axios, nodemailer, i18next-http-backend, multer, tar) on main are >= the pinned versions on stable. If stable has a newer pinned version (e.g. an emergency CVE backport main hasn't picked up), take stable's pin.
- README.md — keep stable's version if it has had a recent rewrite that main didn't pick up; otherwise take main's.
- CHANGELOG.md — keep stable's; release-please regenerates entries on its next stable cut from the commits going forward.
- .release-please-manifest.json — keep stable's; release-please owns this file.
- Any other auto-merged file — spot-check that the auto-merge produced something sensible, especially for security-sensitive files (backend/src/middleware/, backend/src/utils/tokenUtils.js).
Wait for CI on the PR. All ten checks (the original eight plus merge-backend and merge-frontend) must be green. If anything fails, fix on the release branch (NOT on main — main has already moved on).
Merge. Standard merge commit, not squash — the PR's history (the individual feature commits) carries forward into stable's log.
release-please picks it up. Within minutes, release-please will open a new chore(stable): release X.Y.Z PR proposing the stable release. Review the auto-generated CHANGELOG.md entries for accuracy, edit if needed, and merge. That merge creates the vX.Y.Z git tag, publishes Docker images on the :stable and :latest tags, and creates the GitHub Release page.
Close the loop. Bulk-close any bug issues that were fixed-but-not-closed and now appear in the released changelog. Reference the merge commit so reporters know which version contains the fix.

Hotfix path (backport to current stable)

If a critical bug or security issue affects the current stable and main has moved too far for a full promotion to be appropriate, backport just the fix:

Create a security/cve-backport-X.Y.Z or fix/critical-X.Y.Z branch off stable.
Cherry-pick or hand-write the minimal fix.
Open a PR to stable with the smallest possible diff.
After merge, release-please will propose a patch-level stable release (e.g. v3.55.1).
Forward-port the fix to main if it isn't already there. Otherwise the next full promotion will reintroduce the bug.

PR #412 ("backport 18 dependency CVE patches from beta") is a worked example of this path (predates the rename; the mechanics are unchanged).

Versioning

PicPeak follows Semantic Versioning with one project-specific convention:

MAJOR bumps are reserved for breaking schema changes that require operator action on upgrade (e.g. a migration that's not safe to auto-apply, an env-var rename that can't be auto-detected).
MINOR bumps for new features, additive schema changes, and any change to the public HTTP API surface.
PATCH bumps for bug fixes and operator-invisible internal changes.
Pre-release suffix (-beta.N) for every main-channel cut; the N counter resets on each new MINOR or MAJOR target. The suffix kept the historical -beta literal even after the branch rename — operators were already pinning to v3.x.y-beta.N and changing the literal would have broken those pins.

release-please derives all of this from conventional commit prefixes (feat:, fix:, BREAKING CHANGE:, etc.) automatically.

Things that don't go through this process

Documentation-only changes can land on either stable or main directly (no release cut needed); release-please will pick them up on the next regular release.
Test-only changes — same.
CI / workflow changes — same, but be aware they take effect on the branch they land on, so a CI fix targeting main won't fix a broken stable-channel workflow until the next promotion.

When this doc is wrong

If you find yourself working around something here, update the doc before doing the workaround. The point of a written process is that future-you doesn't have to remember the workaround.

8.3 KiB Raw Permalink Blame History Unescape Escape