From 28fc991906fec5cc911bc0a9a45cb34eef2ecb3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Lesimple?= Date: Sun, 13 Sep 2026 12:58:48 +0200 Subject: [PATCH] doc: update dev documentation --- DEVELOPMENT.md | 32 ++++++++++++++++---------------- RELEASE.md | 19 ++++++++++++------- 2 files changed, 28 insertions(+), 23 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 601dc70..4b64a52 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -33,30 +33,30 @@ These terms have precise meanings throughout the codebase and output: ## Branch Model -The project uses 4 branches organized in two pipelines (production and dev/test). Developers work on the source branches; CI builds the monolithic script and pushes it to the corresponding output branch. +The project uses five branches, with separate experimental and production pipelines. Developers work on `test` and `source`; CI builds the monolithic script and pushes it to the corresponding build output branch. The production script is then promoted from `source-build` to `master`. | Branch | Contents | Pushed by | |--------|----------|-----------| -| **`test`** | Dev/test source (split files + Makefile) | Developers | +| **`test`** | Experimental patches and/or test patches for reported issues (split files + Makefile) | Developers | | **`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) | `release` workflow, synced from `source-build` | +| **`source`** | Source code destined for `master` (split files + Makefile) | Developers | +| **`source-build`** | Monolithic pre-production script (built artifact) | CI from `source` | +| **`master`** | Latest script believed to be production-grade, plus master-only artifacts | Script promoted by the `release` workflow 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 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. +- **`test`** is used for experimental patches and/or test patches related to reported issues. Its history is not guaranteed to be linear, and it is usually not merged into `source`. +- **`source`** has a linear history and contains code that will make it to `master`. Accepted changes from experiments or issue testing are applied selectively, preserving that linear history. +- **`test-build`** and **`source-build`** are CI-managed build output branches. Users can pull `test-build` to try experimental or issue-specific patches; `source-build` holds the assembled script from `source` before promotion to production. +- **`master`** contains the latest version of `spectre-meltdown-checker.sh` believed to be production-grade. It is the preexisting production branch that users pull from and cannot be renamed. It also contains master-only artifacts, such as workflows. +- **`source-build`** is never merged directly into `master`. The manual `release` workflow copies every top-level entry present on `source-build` except `.github/` into a pull request against `master`. This includes the assembled `spectre-meltdown-checker.sh`, documentation and container files, while preserving `master`'s own workflows. The changes reach `master` when that pull request is merged. See [RELEASE.md](RELEASE.md) for the release procedure. 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 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. +1. Develop production-bound changes on `source`, keeping its history linear. +2. When experimentation or testing a reported issue is needed, use `test`. CI builds the script and pushes it to `test-build` for testing. +3. Apply accepted experimental fixes selectively to `source`, preserving its linear history. Usually, `test` itself is not merged into `source`. +4. CI builds the script from `source` and pushes it to `source-build` for pre-production validation. +5. Once the script is believed to be production-grade, run the manual `release` workflow on `master` with `action = sync-from-source-build`, then review and merge the resulting artifact-sync pull request. +6. To publish a formal GitHub release, separately run the workflow on `master` with `action = draft-github-release`, then review and publish the draft. Updating `master` does not require publishing a GitHub release. See [RELEASE.md](RELEASE.md) for the full procedure. ## Versioning diff --git a/RELEASE.md b/RELEASE.md index e1dca41..d05e79e 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -42,11 +42,14 @@ against the `master` branch. ### 1. `sync-from-source-build` -Copies every top-level entry on `source-build` **except `.github/`** +Opens or updates a pull request against `master` copying every top-level entry +present 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. +`docker-compose.yml`). Each selected path is mirrored exactly, including +deletions and renames within directories. Top-level entries that exist only on +`master` are left untouched. `master`'s own `.github/` — its master-only CI — is +never touched. Nothing lands on `master` until the pull request is reviewed +and merged. 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. @@ -70,7 +73,8 @@ commit since. Treat it as a starting point and edit it before publishing. 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`. + sync-from-source-build`. Review and merge the resulting pull request into + `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 @@ -82,5 +86,6 @@ Steps 2 and 3 are decoupled on purpose: you can refresh `master` from ## 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`). +- Before merging a sync pull request: close it without merging. +- After merging a bad sync: `master` history is intact — revert the sync with + a normal `git revert` (never force-push `master`).