Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

SysForge is an Arch Linux build and maintenance suite with compiler optimization as a first-class concern. It manages AUR and custom package builds using rule-based compiler flag profiles, tracks build state for update detection, and automates the full build lifecycle — from fetching PKGBUILDs to installing profiled packages. Pacman owns the package database; SysForge owns the build configuration layer above it.

SysForge manages the profiled AUR-helper surface (install, update, and manage AUR and custom packages with system-tuned profiled builds) and a full bootstrap pipeline (stages 1–3: install via archinstall, hardware detection, configure) that automates a fresh Arch install from the ISO. Current release is **<!--version-->v3.5.0<!--/version-->**; per-release changes are recorded in `docs/release-notes/`.
SysForge manages the profiled AUR-helper surface (install, update, and manage AUR and custom packages with system-tuned profiled builds) and a full bootstrap pipeline (stages 1–3: install via archinstall, hardware detection, configure) that automates a fresh Arch install from the ISO. Current release is **<!--version-->v4.0.0<!--/version-->**; per-release changes are recorded in `docs/release-notes/`.

---

Expand Down Expand Up @@ -4184,16 +4184,18 @@ with the release script's own preflight, which is the blocking gate.

Releases are driven by three Makefile targets — `make release-major`, `make release-minor`, `make release-patch` — each of which calls `tools/release.sh --bump=<level>`. The script handles the full flow end-to-end with a single up-front summary + approval prompt and one mid-run pause for the manual tag push. Phases:

1. **Bump, commit, tag.** Rewrites `pyproject.toml` (the single source of truth for version), `PKGBUILD` `pkgver=`, `PKGBUILD-git` `pkgver=` (leading `X.Y.Z` only — the `.r0.g0000000` suffix is preserved as the placeholder for the dynamic `pkgver()`), the `<!--version-->vX.Y.Z<!--/version-->` markers in `README.md`, `DESIGN.md`, **and the generated marker's source `docs/design/00-header.md`** (DESIGN.md is generated — rewriting only the output would be reverted by the next `make design`), regenerates `uv.lock` (via `uv lock`) and `man/sysforge.1` (via `make man`), renames the release-notes accumulator `docs/release-notes/unreleased.md` to `vX.Y.Z.md` (title stamped with version + date) and reseeds a fresh accumulator, then makes a single **GPG-signed** `release: vX.Y.Z` commit (which includes both the renamed `docs/release-notes/vX.Y.Z.md` and the reseeded `unreleased.md` — see *Release notes* below) and creates a **signed annotated tag** (`git tag -s`, immediately verified with `git tag -v`).
2. **Push pause.** Prints `git push origin main && git push origin vX.Y.Z` and waits on ENTER. The user pushes manually (releases are deliberate, not background events). The script verifies the tag is on `origin` before continuing.
3. **Post-tag artifacts + signed release.** Downloads the GitHub tarball, records its sha256 **and GPG-signs it** (detached armored `.asc`), updates `sha256sums=` in `PKGBUILD` to the two-element form (tarball hash + `SKIP` for the signature source), **publishes the GitHub release** (`gh release create`, or `gh release upload --clobber` on resume) with the `.asc` + `SHA256SUMS` + `SHA256SUMS.asc` assets, then **validates both `PKGBUILD` and `PKGBUILD-git` in a clean chroot** (the release must exist first — the stable PKGBUILD's signature source points at the release download URL, so `makepkg` fetches and verifies the `.asc` during validation), regenerates `.SRCINFO` and `.SRCINFO-git` (both gitignored — local artifacts only), and makes a second signed `release: vX.Y.Z sha256` commit (the `.SRCINFO` files do not get committed).
4. **Final instructions.** Confirms the signed GitHub release is published, then prints `git push origin main` and the `git clone`/`cp`/`commit`/`push` sequence for the `sysforge` and `sysforge-git` AUR repos. The user runs those manually.
Every release is cut on its own `release/vX.Y.Z` branch, never pushed to `main` directly: the `main` ruleset requires a pull request (see the CI paragraph above). That release PR is the one merge into `main` made with a **merge commit**, not a squash. A squash would rewrite the signed `release:` commit, leaving the signed tag on a commit `main` never contains. `git describe` in `PKGBUILD-git`'s `pkgver()` would then keep naming the previous tag, and `--resume`'s ancestor check would fail. The ruleset therefore allows both `squash` (ordinary PRs) and `merge` (release PRs).

1. **Bump, commit, tag.** Switches to a new `release/vX.Y.Z` branch (preflight requires starting on `main` and refuses if that branch already exists), then rewrites `pyproject.toml` (the single source of truth for version), `PKGBUILD` `pkgver=`, `PKGBUILD-git` `pkgver=` (leading `X.Y.Z` only — the `.r0.g0000000` suffix is preserved as the placeholder for the dynamic `pkgver()`), the `<!--version-->vX.Y.Z<!--/version-->` markers in `README.md`, `DESIGN.md`, **and the generated marker's source `docs/design/00-header.md`** (DESIGN.md is generated — rewriting only the output would be reverted by the next `make design`), regenerates `uv.lock` (via `uv lock`) and `man/sysforge.1` (via `make man`), renames the release-notes accumulator `docs/release-notes/unreleased.md` to `vX.Y.Z.md` (title stamped with version + date) and reseeds a fresh accumulator, then makes a single **GPG-signed** `release: vX.Y.Z` commit (which includes both the renamed `docs/release-notes/vX.Y.Z.md` and the reseeded `unreleased.md` — see *Release notes* below) and creates a **signed annotated tag** (`git tag -s`, immediately verified with `git tag -v`).
2. **Push pause.** Prints `git push -u origin release/vX.Y.Z && git push origin vX.Y.Z` and waits on ENTER. The user pushes manually (releases are deliberate, not background events). The script verifies the tag is on `origin` before continuing. Phase 3 only needs the tag on `origin` (it fetches `archive/vX.Y.Z.tar.gz`), not the commit on `main`, so the release proceeds before the PR merges. Tags are outside the branch ruleset.
3. **Post-tag artifacts + signed release.** Downloads the GitHub tarball, records its sha256 **and GPG-signs it** (detached armored `.asc`), updates `sha256sums=` in `PKGBUILD` to the two-element form (tarball hash + `SKIP` for the signature source), **publishes the GitHub release** (`gh release create`, or `gh release upload --clobber` on resume) with the `.asc` + `SHA256SUMS` + `SHA256SUMS.asc` assets (GitHub caps a release body at 125,000 characters, so a longer `vX.Y.Z.md` is published as its summary, everything above the first `## `, plus a link to the full file at the tag), then **validates both `PKGBUILD` and `PKGBUILD-git` in a clean chroot** (the release must exist first — the stable PKGBUILD's signature source points at the release download URL, so `makepkg` fetches and verifies the `.asc` during validation), regenerates `.SRCINFO` and `.SRCINFO-git` (both gitignored — local artifacts only), and makes a second signed `release: vX.Y.Z sha256` commit (the `.SRCINFO` files do not get committed).
4. **Final instructions.** Confirms the signed GitHub release is published, then points at RELEASE-CHECKLIST Stage 7: push `release/vX.Y.Z` (now carrying the sha256 commit), open the release PR, merge it with `gh pr merge --merge` once `gates` is green, then the `git clone`/`cp`/`commit`/`push` sequence for the `sysforge` and `sysforge-git` AUR repos. The user runs those manually. If `main` moves while the PR is open, the strict status-check rule asks for an up-to-date branch: update it with a merge from `main`, never a rebase, which would rewrite the tagged commit.

**Release signing & downstream verification.** From this release onward every release is GPG-signed end to end with the maintainer key: the commit, the annotated tag, and the source tarball. `tools/release.sh` preflight hard-fails before touching any file if signing is not usable — `git user.signingkey` unset, `commit.gpgsign` not `true`, the secret key not in the keyring, or `gh` missing — so an *unsigned* or unpublishable release can never be produced. The stable `PKGBUILD` declares the maintainer fingerprint in `validpgpkeys` and adds the detached signature as a second `source` entry (`…releases/download/vX.Y.Z/sysforge-X.Y.Z.tar.gz.asc`, paired with `SKIP` in `sha256sums`), so `makepkg` verifies the maintainer signature at install time — closing the gap where the only integrity link was a hash the release script computed itself. The repo ships a placeholder fingerprint sentinel (`REPLACE_WITH_MAINTAINER_KEY_FINGERPRINT`); `check_shipped` tolerates it so dev gates pass before a key exists, but the release preflight refuses to publish while it is present. The `-git` (VCS) package tracks a git clone rather than a release tarball, so it carries no `validpgpkeys`/`.asc` (its provenance is the signed tag); `check_shipped pkgbuild_parity` allows `validpgpkeys` to be stable-only, and the `pkgbuild` group permits `SKIP` only when paired with a `.asc`/`.sig` source. Users verify releases per the *Verifying releases* section of `README.md`.

**Release notes.** Notes are authored **incrementally**, not reconstructed at release time. Each landing commit that completes a ROADMAP item appends its entry — under the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) category headings (`Added` / `Changed` / `Deprecated` / `Removed` / `Fixed` / `Security`) — to the running accumulator `docs/release-notes/unreleased.md` in that same commit. An entry carries ROADMAP.md's own entry shape: it leads with its roadmap ID (``- **`<ID>` — <title sentence>.** <body>``) and is separated from its neighbour by a `---` rule, so one item reads on its own rather than running into the next, and an item looks the same on the backlog as it does in the notes. One item routinely ships several distinct user-visible changes, so when its ID files more than one entry **within the same section** each lead carries a `(n/N)` facet suffix (``- **`<ID>` (n/N) — <title sentence>.**``), numbered in document order — the entry then states up front that it is one facet of a larger item rather than reading as a duplicate filing. Cross-section repeats carry none: one Keep a Changelog entry cannot span `Changed` and `Removed`, and a `(2/3)` under a heading the reader arrives at with no memory of `(1/3)` explains nothing. `make check-standards` lints the accumulator under the same vocabulary — plus the ID-first lead, the facet suffix (present iff the ID repeats in-section, `1..N` once each, denominator matching the actual count) and the ascending-ID ordering, with the facet as the same-ID tiebreak — so entries are validated as they land. The pre-flight in `tools/release.sh` **hard-fails** when the accumulator is missing or holds no authored `## ` sections, mirroring the check-shipped/check-personal/check-design gates. Phase 1 **renames** the accumulator to `docs/release-notes/vX.Y.Z.md`, stamps its `# ` title with the version + ISO date, reseeds a fresh accumulator, and commits both as part of the `release: vX.Y.Z` commit; Phase 4 prints the `gh release create` command that publishes the versioned file. Before releasing, the `/release-notes` repo skill reconciles/lints the accumulated entries against this section's framing (a hookify rule reminds before any `make release-*` invocation); it no longer authors the file from scratch.

If interrupted between phases (Ctrl-C at the push pause, or a transient failure), re-running the same `make release-*` command resumes correctly: the script detects that the tag for the *current* `pyproject.toml` version already exists at HEAD and skips Phase 1. That auto-detection cannot fire once a post-tag failure (e.g. chroot validation) needs fix commits *on top of* the release commit — the tag is no longer at HEAD, and re-running a `--bump` invocation would compute a fresh bump from the already-bumped version. For that case `make release-resume` (`tools/release.sh --resume`) explicitly finishes the release for the current version: it requires the `vX.Y.Z` tag to exist and be an *ancestor* of a clean HEAD (`git merge-base --is-ancestor`), performs no bump, and re-enters at Phase 3. The ancestor check is deliberately gated behind the explicit flag: after any *completed* release its tag is also an ancestor of HEAD, so ancestor-based auto-detection would misclassify every subsequent fresh release as a resume. To keep a transient post-tag failure from reading as an unrecoverable one, the script arms an `ERR` trap the moment the release becomes *in-flight* (a `--resume`/auto-detected-resume run, or the instant Phase 1 creates the signed tag): any later non-zero exit prints an advisory that the bump/commit/tag are already in place (and possibly pushed/published) and that `make release-resume` finishes it idempotently — so `make`'s bare `Error 255` is reframed rather than mistaken for a from-scratch failure. Failures *before* the tag exists (bad args, pre-flight, version bump) keep the trap silent and exit plainly, since there is nothing tagged to resume.
If interrupted between phases (Ctrl-C at the push pause, or a transient failure), re-running the same `make release-*` command resumes correctly: the script detects that the tag for the *current* `pyproject.toml` version already exists at HEAD and skips Phase 1. That auto-detection cannot fire once a post-tag failure (e.g. chroot validation) needs fix commits *on top of* the release commit — the tag is no longer at HEAD, and re-running a `--bump` invocation would compute a fresh bump from the already-bumped version. For that case `make release-resume` (`tools/release.sh --resume`) explicitly finishes the release for the current version: it requires the `vX.Y.Z` tag to exist and be an *ancestor* of a clean HEAD (`git merge-base --is-ancestor`) on `release/vX.Y.Z` (fix commits belong there so they reach `main` through the release PR), performs no bump, and re-enters at Phase 3. Its clean-tree check tolerates one edit: a `PKGBUILD` whose only change is its `sha256sums` array, which is what a Phase 3 failing after the sha256 rewrite leaves behind and what Phase 3 rewrites again. Both sides are compared with that array removed, so any other `PKGBUILD` edit still blocks the resume. The ancestor check is deliberately gated behind the explicit flag: after any *completed* release its tag is also an ancestor of HEAD, so ancestor-based auto-detection would misclassify every subsequent fresh release as a resume. To keep a transient post-tag failure from reading as an unrecoverable one, the script arms an `ERR` trap the moment the release becomes *in-flight* (a `--resume`/auto-detected-resume run, or the instant Phase 1 creates the signed tag): any later non-zero exit prints an advisory that the bump/commit/tag are already in place (and possibly pushed/published) and that `make release-resume` finishes it idempotently — so `make`'s bare `Error 255` is reframed rather than mistaken for a from-scratch failure. Failures *before* the tag exists (bad args, pre-flight, version bump) keep the trap silent and exit plainly, since there is nothing tagged to resume.

The version markers in `README.md` and `DESIGN.md` wrap the single live version token (`<!--version-->vX.Y.Z<!--/version-->`); only it rotates per release. Each document must carry exactly one such marker. The `versions` check group below enforces lockstep across all marker locations; release pre-flight refuses to run if the markers (or the `pkgver` lines, or any other version-bearing field) are out of sync.

Expand Down
4 changes: 2 additions & 2 deletions PKGBUILD
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Maintainer: Keith Raghubar <aur.archlinux.org.buckskin000@passmail.net>

pkgname=sysforge
pkgver=3.5.0
pkgver=4.0.0
pkgrel=1
pkgdesc="AUR helper that builds and tracks packages tuned to your CPU with PGO, BOLT and LTO"
arch=('any')
Expand Down Expand Up @@ -48,7 +48,7 @@ backup=(
validpgpkeys=('23774499080F9288FEFB49CE7AAE22E6E1B4B22C')
source=("$pkgname-$pkgver.tar.gz::$url/archive/v$pkgver.tar.gz"
"$pkgname-$pkgver.tar.gz.asc::$url/releases/download/v$pkgver/sysforge-$pkgver.tar.gz.asc")
sha256sums=('a9e99f76a79b537af1e75f7578c4aeffd5857fb472b06d345e395769e6b288ed'
sha256sums=('e9b748430796edfd4ed25f545d2415f4a00a97d88ad1ba9c24791efa1e1fbe69'
'SKIP')

build() {
Expand Down
2 changes: 1 addition & 1 deletion PKGBUILD-git
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Maintainer: Keith Raghubar <aur.archlinux.org.buckskin000@passmail.net>

pkgname=sysforge-git
pkgver=3.5.0.r0.g0000000 # updated dynamically by pkgver()
pkgver=4.0.0.r0.g0000000 # updated dynamically by pkgver()
pkgrel=1
pkgdesc="AUR helper that builds and tracks packages tuned to your CPU with PGO, BOLT and LTO (git)"
arch=('any')
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ SysForge is an AUR helper that builds and tracks packages tuned to your CPU. Eve

![On a fresh install, sysforge build cbonsai -si reviews the AUR package's PKGBUILD, builds it with -march=native and installs it; sysforge update then finds nothing to rebuild](docs/assets/quickstart.gif)

<sub><!--version-->v3.5.0<!--/version--></sub>
<sub><!--version-->v4.0.0<!--/version--></sub>

---

Expand Down
Loading
Loading