RFC-0022: Release Automation and Unified Canary/Stable Branches

[github-actions[bot]]

📄 RFC Doc: 0022-release-automation.md

---

Release Automation and Unified Canary/Stable Branches

Authors: @lalitm

Status: Draft

Problem

Perfetto's release process today is a patchwork of partially-automated scripts
and manual steps spread across three loosely-coupled pipelines — the SDK/native
binaries, the UI, and the Python package. Each has its own versioning model,
its own branching convention, and its own notion of "canary" vs "stable". The
result is a release workflow that is:

1. Manual and error-prone. tools/release/release_perfetto.py requires a
   human to run it locally, answer prompts, wait on LUCI builds, hand-upload
   artifacts, and manually create the GitHub release. A single release is a
   multi-hour, multi-terminal babysitting exercise.

2. Fragmented across artifacts. The SDK uses releases/vX.x maintenance
   branches and vX.Y tags. The UI uses ui-canary / ui-stable branches
   plus a channels.json file in main that pins each channel to a specific
   SHA. The Python package uses a hardcoded version string in python/setup.py
   and a separate release_python.py script that is not run as part of the
   normal release flow. These three things drift: the UI on ui-stable may
   correspond to a completely different commit than the SDK tagged vX.Y.

3. No clear "release-in-progress" state. There is no single branch a
   contributor can look at and say "this is what v54 will contain". The
   decision of what goes into v54 is implicit in whoever ran the release
   script and when.

4. UI channels driven by a file, not a branch. channels.json was a
   pragmatic choice when it was introduced but it means:

   • Cherry-picks to a channel require two PRs (one to the channel branch,
     one to main to bump the SHA).
   • The source of truth for "what is canary" is a JSON file, not the branch
     named ui-canary.
   • Anyone with commit access to main can redirect a channel.

5. No PyPI automation. Python releases happen rarely and out-of-band from
   SDK releases. The version in setup.py is updated by hand, and pushing to
   PyPI is a manual twine upload.

6. LUCI build completion is not observable from GitHub. Builds are
   triggered by tag push (refs/tags/upstream/v.+) but there is no hook back
   into the GitHub release. Whoever cut the release has to watch LUCI, wait
   for all four platforms to finish, download the artifacts, and upload them
   to the release by hand.

We want to get to a world where cutting a release is a small number of button
clicks in the GitHub UI, where the branch state at any moment tells you
exactly what is in flight, and where the SDK, UI, and Python package move
together.

Decision

Pending.

Design

Summary

Replace the per-release releases/vX.x branches and the UI's channels.json
file with two long-lived branches — canary and stable — that are shared by
the SDK, the UI, and the Python package. All transitions between branches
(main → canary, canary → stable) are triggered by clicking
workflow_dispatch buttons in the GitHub Actions UI. The stable promotion
is what tags the release, and the tag push is the single event that fans out
to LUCI (native binaries), Cloud Build (UI), and GitHub Actions (PyPI + GitHub
Release creation). LUCI artifact attachment is reconciled by a final
human-triggered "finalize release" button.

Independent artifact producers (LUCI, Cloud Build, GH Actions) converge on
the same GitHub release using a "create draft if missing, else upload to
existing" idempotent pattern, so no producer needs to wait for any other.

Branches

Three long-lived branches, each protected (no direct pushes; PRs only):

Branch	Represents	Updated by
main	HEAD of development	normal PR merges
canary	Next release, feature-locked	button: main → canary (fast-forward)
stable	Current shipping release	button: canary → stable (fast-forward + tag)

The existing releases/vX.x branches are frozen in place as historical
artifacts. We do not create new ones and we do not backport to them. This
matches current practice: we already only support the latest release.

The existing ui-canary and ui-stable branches go away, replaced by the
unified canary / stable. The channels.json file is deleted.

Version numbering

The version is derived from the top of the CHANGELOG file, as today, via
tools/write_version_header.py. This now becomes the source of truth for
every artifact:

• Native binaries: vX.Y (C++ header generated at build time).
• UI: vX.Y-<9-char-SHA> (as today).
• Python package: 0.X.Y (auto-derived from CHANGELOG at wheel-build time;
  the hardcoded string in python/setup.py is removed). The 0. prefix
  keeps the package in the pre-1.0 series while encoding the Perfetto
  release in the minor/patch components, giving a monotonic jump from the
  current 0.16.0.

The CHANGELOG is bumped in a normal PR to main before the main → canary
fast-forward. The person cutting canary is responsible for confirming that
CHANGELOG already contains the intended vX.Y entry.

Release lifecycle

                 main
                  │
                  │  (1) click "Cut canary"  ─── fast-forward canary to main SHA
                  ▼
                canary  ◄────── cherry-pick PRs target canary directly
                  │
                  │  (2) UI Cloud Build auto-deploys canary channel
                  │      on every push to `canary`
                  │
                  │  (3) click "Promote canary to stable"
                  ▼
                stable  ──► tag vX.Y pushed as part of the same action
                  │
                  │  (4) tag push triggers in parallel:
                  │        - LUCI official builds (4 platforms)
                  │        - Cloud Build UI deploy to stable channel
                  │        - GH Actions: build+publish PyPI wheel
                  │        - GH Actions: create draft GitHub release
                  │
                  │  (5) click "Finalize release" once LUCI is done
                  ▼
            artifacts attached to draft
                  │
                  │  (6) human reviews notes and clicks "Publish" in the
                  │      GitHub UI
                  ▼
                 released

The four buttons

All four are workflow_dispatch workflows under .github/workflows/.

Button 1: cut-canary.yml. Creates a merge commit on canary whose
tree equals the current tip of main, using the git merge -s ours + git read-tree -m -u pattern (same approach as the existing
merge-main-to-canary.yml). This always moves forward (no force-push
needed) and handles the normal case where cherry-picks on canary have
different SHAs than their main counterparts, so a true "fast-forward"
would never succeed after one release cycle.

Convention: every fix lands on main first and is then cherry-picked to
canary. Anything that exists only on canary will be silently dropped at
the next cut, because we're replacing canary's tree with main's. The
dropped commit is still in canary's git history and can be re-cherry-picked
if needed. Opens no PR; the push itself is the event. Pushes to canary
trigger Cloud Build to redeploy the canary UI.

Button 2: promote-stable.yml. Applies the same tree-replacing merge
pattern to push canary's tree onto stable, then creates and pushes the
vX.Y tag (version read from CHANGELOG) pointing at the resulting
stable HEAD. This single action is what triggers every downstream build.

Button 3: finalize-release.yml. Takes a version input (e.g. v54.0).
Downloads the LUCI artifacts from GCS, verifies they match the expected
manifest, and attaches them to the draft GitHub release. Leaves the
release as a draft — a maintainer reviews the release notes and clicks
"Publish" manually from the GitHub UI. Idempotent — safe to re-run.

Cherry-picks are opened as regular PRs targeting canary. There is no
"hotfix directly to stable" path: even emergency fixes go main → canary
→ stable via the normal buttons. This keeps the invariant that stable is
always an ancestor of canary, which in turn keeps the promotion button a
pure fast-forward.

Artifact flow on tag push

The vX.Y tag push is the single event that fans out. Four independent
producers each converge on the same GitHub release using the
"create-if-missing, upload-on-exists" pattern:

if gh release view "$TAG" > /dev/null 2>&1; then
  gh release upload "$TAG" <files> --clobber
else
  gh release create "$TAG" --draft --generate-notes <files>
fi

Producers:

1. LUCI native builds (Linux, macOS, Windows, Android). Triggered as
   today by the refs/tags/upstream/v.+ scheduler rule. Each builder already
   uploads to gs://perfetto-luci-artifacts/<git-revision>/<arch>/<binary>
   (with a parallel latest/ alias), and the SDK source zips land at
   gs://perfetto-luci-artifacts/<version>/sdk/. Button 3 reconciles these
   existing paths into the GitHub release — no new bucket or layout is
   required.

2. UI Cloud Build. The existing trigger (formerly keyed on changes to
   channels.json) is re-keyed to fire on pushes to the stable branch.
   Builds the UI from stable HEAD and deploys to the stable channel.

3. PyPI publish workflow (publish-pypi.yml). Triggered by tag push.
   Builds a pure-Python wheel with version derived from CHANGELOG, publishes
   to PyPI using OIDC trusted publishing (no long-lived token). Does not ship
   native binaries in v1.

4. GitHub Release draft (draft-release.yml). Triggered by tag push.
   Creates the draft release; the body is pre-populated with the
   corresponding vX.Y section of the CHANGELOG verbatim, so even if no
   human touches it the release still has useful content. The draft exists
   from the moment the tag is pushed; LUCI artifacts are attached
   asynchronously.

   Release notes themselves are human-authored, not automated. Before
   clicking finalize-release a maintainer is expected to edit the draft's
   body in the GitHub UI to replace the raw CHANGELOG with prose release
   notes — thematic grouping, highlights, links to docs, etc. The existing
   tools/release/gen_release_notes.py script (an AI-prompt generator for
   exactly this authoring step) is retained for this workflow. It is
   deliberately not invoked from CI: the release notes are a curated
   artifact, and the cost of a bad auto-generated announcement is higher
   than the cost of one manual editing step per release.

LUCI → GitHub bridge

The tag-push → LUCI path already works today. The missing piece is notifying
GitHub when LUCI is done so artifacts can be attached.

For v1 we deliberately avoid a webhook. Instead, button 3 (finalize-release)
is a manually-triggered GH Actions workflow that a human clicks once LUCI is
green. It reads from the existing gs://perfetto-luci-artifacts/ paths
(which are world-readable via storage.cloud.google.com) and uploads into
the draft release. This keeps the secret surface minimal — GH Actions already
has GITHUB_TOKEN, and no GCS credential is needed since the bucket is
public — at the cost of one extra click per release.

UI: channels.json removal

The channels.json file and the associated ui-canary / ui-stable branches
go away. The UI Cloud Build trigger is reconfigured to build:

• autopush channel on every push to main (as today).
• canary channel on every push to canary.
• stable channel on every push to stable.

Because canary and stable are protected branches, there is no way to
accidentally redirect a channel without going through a PR, which is a
strictly stronger guarantee than channels.json provides today.

The UI version string (vX.Y-<SHA>) continues to be computed from CHANGELOG

• branch HEAD SHA at build time, so it remains meaningful on every channel.

channels.json is not a public API, but as it has lived in the repo for a
long time the removal will be called out in the CHANGELOG and in the first
release's GitHub release notes.

Python packaging

For v1, the PyPI release is a pure-Python wheel (no bundled
trace_processor_shell) on stable tags only. The version is auto-derived
from CHANGELOG, killing the hardcoded 0.16.0 in python/setup.py.

Bundling trace_processor_shell into the wheel — so that pip install perfetto gives you a working CLI — is an attractive future step but has
non-trivial packaging implications (multi-platform wheels, LUCI artifact →
PyPI pipeline, manylinux compatibility). Out of scope for v1.

What happens to existing scripts

• tools/release/release_perfetto.py: deleted. Its responsibilities are
  split across the four GH Actions workflows.
• tools/release/release_python.py: deleted. Replaced by publish-pypi.yml.
• tools/release/gen_release_notes.py: retained. Invoked by the draft-release
  workflow if --generate-notes is insufficient.
• tools/release/package-github-release-artifacts: retained, invoked from
  LUCI builders to produce the per-platform zips.
• tools/release/roll-prebuilts: unchanged (separate concern: rolling
  prebuilts into the repo, not cutting a release).

Protected branch configuration

• main, canary, stable: all require PR, no direct push, no
  force-push, require status checks.
• canary and stable additionally require a review from a designated
  release-approver group (to prevent drive-by cherry-picks).
• The vX.Y tag namespace is restricted to being created by the
  promote-stable.yml workflow's GH App / token (not by humans).

Alternatives considered

Keep releases/vX.x maintenance branches

Pro:

• Familiar. Allows in-theory backporting.

Con:

• We don't actually backport in practice — the last non-trivial backport was
  years ago.
• Forces the human to decide "is this a new major or minor" at release time,
  which has no meaning for how we actually develop.
• Branches accumulate indefinitely; the repo has 15+ of them already.

Keep channels.json

Pro:

• Already works.
• Channel redirection is a single-file PR.

Con:

• Indirection: ui-stable branch exists but is not the source of truth.
• Two PRs for every cherry-pick.
• Different mental model from the SDK side of the release.

LUCI → GitHub via webhook instead of manual finalize button

Pro:

• One fewer button click.
• Release publishes automatically the moment the last platform finishes.

Con:

• Requires standing up a Cloud Function (or similar) with a GitHub App
  credential.
• Adds a new failure mode (webhook delivery).
• v1 has humans in the loop anyway for the two earlier buttons, so adding
  one more at the end is marginal.

Revisit once the rest of the flow is proven.

Tag on canary cut instead of on stable promotion

Pro:

• Artifacts would be buildable on canary, giving us pre-release binaries.

Con:

• Two tags per release (vX.Y-canary, vX.Y) is more machinery.
• LUCI builds are expensive; building twice per release doubles the spend for
  marginal benefit.
• The UI already provides a canary channel with real user exposure; we don't
  need binary prereleases.

Monorepo-style unified version (e.g. 54.0.0 everywhere)

Pro:

• Uniform across SDK, UI, Python.

Con:

• Breaks existing vX.Y convention and existing consumers' parsers.
• Python's X.Y.Z semantics don't quite map (we never ship .Z patch
  versions).

Keep the existing vX.Y for SDK/UI; map it to 0.X.Y for Python.

Open questions

None at this time.

---

💬 Discussion Guidelines:

• This discussion is automatically synced with the RFC document
• Please provide constructive feedback and suggestions

[github-actions[bot]]

📝 RFC Document Updated

View changes: Commit History

[github-actions[bot]]

📝 RFC Document Updated

View changes: Commit History

[github-actions[bot]]

📝 RFC Document Updated

View changes: Commit History

[github-actions[bot]]

📝 RFC Document Updated

View changes: Commit History