From 1161089b2e5c1e03cb8c04d94dfb7ad133af49e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Lesimple?= Date: Thu, 30 Jul 2026 14:01:30 +0200 Subject: [PATCH] doc: document path-scoped release flow and update branch model Add RELEASE.md describing the manual sync -> draft -> publish release procedure Update DEVELOPMENT.md's Branch Model to reflect that source-build is copied onto master by the manual `release` workflow instead of merged via PR. --- DEVELOPMENT.md | 8 +++-- RELEASE.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+), 3 deletions(-) create mode 100644 RELEASE.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 6043177..e4d6c9e 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -41,20 +41,22 @@ The project uses 4 branches organized in two pipelines (production and dev/test) | **`test-build`** | Monolithic test script (built artifact) | CI from `test` | | **`source`** | Production source (split files + Makefile) | Developers | | **`source-build`** | Monolithic test script (built artifact) | CI from `source` | -| **`master`** | Monolithic production script (built artifact) | PR by developers from `source-build` | +| **`master`** | Monolithic production script (built artifact) | `release` workflow, synced from `source-build` | - **`source`** and **`test`** contain the split source files and the Makefile. These are the branches developers commit to. - **`master`**, **`source-build`** and **`test-build`** contain only the monolithic `spectre-meltdown-checker.sh` built by CI. Nobody commits to these directly. - **`master`** is the preexisting production branch that users pull from. It cannot be renamed. - **`test-build`** is a testing branch that users can pull from to test pre-release versions. -- **`source-build`** is a preprod branch to prepare the artifact before merging to **`master`**. +- **`source-build`** is a preprod branch to prepare the artifact before releasing it to **`master`**. It is a build *output* branch and is never merged into `master`; instead the assembled files are copied across by the manual `release` workflow (see [RELEASE.md](RELEASE.md)), which keeps `master`'s own CI workflows untouched. Typical workflow: 1. Feature/fix branches are created from `test` and merged back into `test`. 2. CI builds the script and pushes it to `test-build` for testing. 3. When ready for release, `test` is merged into `source`. 4. CI builds the script and pushes it to `source-build` for production. -5. Developer creates a PR from `source-build` to `master`. +5. Developer runs the manual `release` workflow to sync `source-build`'s + assembled files onto `master` and draft a GitHub release. See + [RELEASE.md](RELEASE.md) for the full procedure. ## Versioning diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..e1dca41 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,86 @@ +# Releasing + +This document describes how a production release reaches the `master` branch +and how a GitHub release is published. It complements the **Branch Model** +section of [DEVELOPMENT.md](DEVELOPMENT.md). + +This file lives only on the `source`/`test` development branches. It is **not** +part of `dist/`, so it never reaches `source-build` or `master` — users who +`git clone` the `master` branch onto their servers get only the files needed to +run the tool. + +## Why `master` is not a merge target + +`master` plays two roles at once: + +- It is the **distribution branch** — users clone it directly onto their + servers, so it must stay minimal (just the monolithic script and the few + files needed to run/build the container). +- It is the repository's **default branch**, which is the only place GitHub + runs *scheduled* workflows from. The `autoupdate`, `stale` and `vuln-watch` + workflows are therefore **master-only** and deliberately kept off the + `source`/`test` line (see commit "remove from test branch workflows that must + live on master"). + +`source-build` is a build **output** branch and does **not** carry those +master-only workflows (the build's `rsync --delete` strips `.github/` down to +what `source` ships). Merging the whole `source-build` tree into `master` would +therefore drag the *absence* of those workflows into `master`, producing +recurring `modify/delete` conflicts — and, worse, a clean merge could silently +delete them when they hadn't been edited since the last release. + +So we never merge `source-build` into `master`. Instead we **copy only the +assembled artifact files** across, and cut GitHub releases from `master` +directly. + +## The `release` workflow + +`.github/workflows/release.yml` (which, like the other master-only workflows, +lives **only on `master`**) is triggered manually via `workflow_dispatch` and +offers two independent actions selected from the `action` dropdown. Run it +against the `master` branch. + +### 1. `sync-from-source-build` + +Copies every top-level entry on `source-build` **except `.github/`** +(`spectre-meltdown-checker.sh`, `README.md`, `doc/`, `Dockerfile`, +`docker-compose.yml`) onto `master` as a single commit, mirroring exactly +(deletions and renames included). `master`'s own `.github/` — its +master-only CI — is never touched. + +The script's contents are copied byte-for-byte, so its `VERSION` (generated by +the `source-build` build) is preserved unchanged. No version bump happens here. + +The job is a no-op if `master` is already up to date. + +### 2. `draft-github-release` + +Reads the `VERSION` from the script currently on `master`, and creates a +**draft** GitHub release tagged `v`, with the monolithic script +attached as an asset. Because it is a draft, **no tag is created and nothing is +published** until you press *Publish* in the Releases UI — so this step is fully +reversible. + +The changelog is auto-drafted by locating the `source-build` commit whose built +`VERSION` matches the previous published release, then listing every assembled +commit since. Treat it as a starting point and edit it before publishing. + +## Release procedure + +1. Confirm `source-build` holds the artifact you want to release (CI is green, + version string looks right). +2. Run the **`release`** workflow on `master` with `action = + sync-from-source-build`. Review the resulting commit/diff on `master`. +3. Run the **`release`** workflow on `master` with `action = + draft-github-release`. +4. Open the draft release, review/edit the auto-generated changelog, then + **Publish** it. Publishing creates the `v` tag. + +Steps 2 and 3 are decoupled on purpose: you can refresh `master` from +`source-build` (step 2) without cutting a formal GitHub release yet. + +## Rollback + +- Before publishing: delete the draft release in the UI (no tag exists yet). +- After a bad `sync-from-source-build`: `master` history is intact — revert the + sync commit with a normal `git revert` (never force-push `master`).