Version Sync Automation

FOG_VERSION and FOG_CHANNEL (defined in
packages/web/lib/fog/system.class.php) are computed from git state — the
current branch name, distance from the last tag, and commit counts — rather
than being bumped by hand. See the main repo's README ("Versioning and
branches") for the version format itself
({CodeBaseMajor}.{Major}.{Minor}.{Patch}) and what each branch represents.
This page covers how the version string stays correct on each branch
without anyone bumping it by hand.

The formula lives in one script, split from the write

.githooks/lib/fog-version.sh is the single source of truth for the formula.
Given a branch name, it computes FOG_VERSION/FOG_CHANNEL and prints three
lines: the version, the channel, and whether that differs from what's
currently committed (true/false). It touches no files — purely a
function of git state, safe to run ad hoc (locally or in CI) without leaving
a dirty working tree behind.

.githooks/lib/apply-fog-version.sh <version> <channel> is the only thing
that writes system.class.php — two sed calls, nothing else. Callers
(the local hook, CI) run fog-version.sh, and only call apply-fog-version.sh
when the third line says true. This split exists so:

• the formula (the genuinely error-prone part — see Incident history
  below) and the write (mechanical, effectively foolproof) each live in
  exactly one place, and
• nothing gets written, staged, or committed at all when there's nothing to
  fix, instead of always writing and checking git diff afterward to
  decide whether to commit.

The formula per branch prefix:

Branch prefix	Channel	Version scheme
dev (dev-branch)	(none)	{tag base}.{commits since master}
stable	(none)	Same as dev, but counted from dev-branch instead of HEAD
working (working-1.6)	Beta	{branch suffix}.0-beta.{commits since master}
feature (feature-*)	Feature	{branch suffix}.0-feature.{commits since master}
rc (rc-*)	Release Candidate	{branch suffix}.0-RC-{n}, where n increments by 1 from whatever's currently committed

dev-branch and stable deliberately carry no FOG_CHANNEL line at all
— a clean version string with no channel text, by design. This isn't an
oversight; don't add one. working/feature/rc branches do show a channel
label. Because of this, drift detection only compares channel when a channel
line actually exists on that branch — otherwise every check on dev-branch
would find "drift" against an always-empty value that was never supposed to
be there.

The rc case is intentionally different from the others: it's a manual
per-change counter (each real change to a release candidate bumps -N by
one), not a commit count. That's a deliberate choice for how release
candidates are numbered, not something to make consistent with the
count-based branches. (It shares the same "anticipate the commit" flaw the
count-based branches used to have — every check proposes current + 1
regardless of whether a real change happened, so once an rc-* branch
exists this will need the same kind of fix the count-based branches already
got. No rc-* branch has existed yet to force the issue.)

1. The local pre-commit hook

.githooks/pre-commit calls fog-version.sh on every local commit to
working-1.6, dev-branch, rc-*, and feature-* branches. If the third
line says there's drift, it calls apply-fog-version.sh and stages the
result as part of that same commit; otherwise it does nothing. This is what
most contributors experience day-to-day, and it's why a version bump
usually rides along silently inside an otherwise-unrelated commit rather
than showing up as its own change.

2. The fog-workflows daily sweep

The pre-commit hook is client-side — it never runs for a PR merged through
GitHub's web UI (squash, merge-commit, or rebase), so a version merged that
way can silently go stale. This is backstopped by a single scheduled
workflow:
FOGProject/fog-workflows's check-fog-version.yml
runs daily at 10:10 UTC (plus workflow_dispatch for a one-off or
all-branches run) — just over an hour before
stable-releases.yml's monthly 11:11 UTC run,
so a release day never reads a stale version. Each run:

1. Lists fogproject's branches via the GitHub API and filters to the
   watched patterns (working-1.6, dev-branch, rc-*, feature-* — the
   same set the local hook covers, and not stable, see below).
2. For each match, checks out that branch and runs its own copy of
   fog-version.sh — the same script the local hook calls, not a
   separately-maintained copy of the formula.
3. If the third line says there's drift, runs apply-fog-version.sh and
   pushes a fixup commit directly to that branch (no PR — this is the same
   kind of mechanical correction the local hook already makes without
   review). Otherwise nothing is written, staged, or committed.

There's no stub file living in fogproject for this — the workflow discovers
branches itself via the API, so a new feature-*/rc-* branch is covered
automatically the next time the schedule fires, with nothing to propagate or
forget to add.

Daily rather than hourly exists specifically to bound how often this can
ever run at all — see Incident history.

Run visibility

Each matrix instance writes its own outcome — fixed (old → new version), or
already correct — to $GITHUB_STEP_SUMMARY. GitHub renders every job's
summary together on the run's Summary page, so the state of every watched
branch is visible from one screen without opening individual job logs.
discover-branches also lists what it found watching, so a run's scope is
visible up front too.

Why a fixup commit anticipates its own +1

A fixup commit is itself a real commit on the branch, so if it simply wrote
"the value that's correct right now" it would be wrong the instant it lands
— the next check would see the fixup commit itself as one more commit than
what got written, and "fix" it again. fog-version.sh avoids this with a
two-pass compute: first with the raw commit count; if that already matches
what's committed (the third line is false), nothing happens. If it
doesn't, it recomputes once more with the count incremented by one — the
value that will actually be true once this fix exists — and that's what
gets applied. This converges in exactly one commit no matter how large the
gap is, and is dynamic (a real recount every run), not a fixed offset
applied forever.

Incident history (2026-07-28)

An earlier version of this workflow didn't anticipate its own commit. It
lived as a push-triggered stub in fogproject calling a reusable workflow in
fog-workflows, and its commit-count formula counted its own prior fixup
commits as real drift. A bot-authored push re-triggered the push-triggered
stub, which recomputed a value one higher than it had just committed, and
pushed another fixup — 30 commits landed on dev-branch in about 20 minutes
before it was caught. Moving to a schedule trigger (instead of push) removed
the immediate retrigger, and the two-pass anticipation above removed the
underlying non-convergence, which would otherwise have just repeated once
per scheduled run instead of once per push. The ~150 leftover fixup commits
from that incident were left in dev-branch/working-1.6 history rather
than rewritten away; stable-releases.yml's changelog generation excludes
them by commit-message pattern so they don't spam release notes, but they're
still there in git log for anyone who needs to look.

Two further refinements landed the same day, both about how often and
how visibly this runs rather than the formula itself:

• fog-version.sh used to write system.class.php itself, so running
  it for any reason — including a future "detect only, don't fix" use —
  mutated the working tree as a side effect. Splitting it into a pure
  compute (fog-version.sh) and a separate write (apply-fog-version.sh),
  gated on the compute step's own drift signal, means nothing gets written
  at all when nothing needs to change.
• Hourly was excessive for how rarely real drift actually occurs — every
  run that found nothing to fix was still real CI time spent for no reason,
  and any run that did find drift was one more bot commit than necessary if
  it happened to repeat before a human noticed. Daily (at 10:10 UTC, ahead
  of the monthly release check) caps any real fixup to at most one commit
  per branch per day.

3. stable-releases.yml

stable's version is owned entirely by fog-workflows'
stable-releases.yml
(see Stable Release Workflow for how that
pipeline works end to end), which drives the whole release flow (validation,
tagging, release notes, syncing stable back into dev-branch). The daily
sweep above deliberately excludes stable so the two mechanisms never fight
over the same branch, and runs early enough in the day to stay ahead of it.

See Fog Release for the manual side of cutting a release
(kernel/init/iPXE updates); this page covers only how the version string
itself stays correct.