Stable Release PR For 1.5.10.2482 - 2026-09-11

.githooks/lib/fog-version.sh

@@ -11,18 +11,31 @@
 # (locally or in CI) without leaving a dirty working tree behind. Pair with
 # apply-fog-version.sh to actually write the result somewhere.
 #
-# Usage: fog-version.sh [branch-name]
+# Usage: fog-version.sh [branch-name] [mode]
 #   branch-name defaults to the currently checked out branch.
+#   mode  0     (default) report honestly; if drifted, print the version the
+#               next commit should carry.
+#         1     a commit is being written right now - always print the
+#               version that commit should carry. Used by pre-commit.
+#         head  print what the commit that ALREADY EXISTS should carry, with
+#               no +1 - i.e. verify rather than write.
+#
+#   No local hook calls this any more: FOG_VERSION is written only on a base
+#   branch, after a merge, by CI. See the header of .githooks/pre-commit.
 
 set -e
 
 project_dir=$(git rev-parse --show-toplevel)
 system_file="$project_dir/packages/web/lib/fog/system.class.php"
 
 gitbranch="${1:-$(git branch --show-current)}"
-local="${2:-0}"
+mode="${2:-0}"
 
-gitcom=$(git rev-list --tags --no-walk --max-count=1)
+# Release tags only. A release tag is the version string itself (1.5.10.2253),
+# so it starts with a digit. Any other tag -- archive/feature-fog2-gui, pushed
+# on 2026-09-06 -- would otherwise become the base version whenever it is the
+# newest tag, and its slash then breaks the sed in apply-fog-version.sh.
+gitcom=$(git rev-list --tags='[0-9]*' --no-walk --max-count=1)
 
 git fetch origin master:master 2>/dev/null || true
 gitcount=$(git rev-list master..HEAD --count)
@@ -46,13 +59,13 @@ compute_version() {
 
     case "$branchon" in
         dev)
-            tagversion=$(git describe --tags "$gitcom")
+            tagversion=$(git describe --tags --match '[0-9]*' "$gitcom")
             baseversion=${tagversion%.*}
             trunkversion="${baseversion}.${count}"
             channel="Patches"
             ;;
         stable)
-            tagversion=$(git describe --tags "$gitcom")
+            tagversion=$(git describe --tags --match '[0-9]*' "$gitcom")
             baseversion=${tagversion%.*}
             count=$(git rev-list master..dev-branch --count) # Get the gitcount from dev-branch instead
             trunkversion="${baseversion}.${count}"
@@ -85,6 +98,16 @@ compute_version() {
 # new commit right now.
 compute_version "$gitcount"
 
+# rc is the one branch type with no count-verifiable answer: it increments
+# off whatever suffix is already committed rather than off a commit count,
+# so the pass above always returns "one more than what is there". For the
+# modes that are about to write a commit that is exactly right. For head
+# mode, which asks whether the committed value is already correct, it would
+# be a permanent false positive - so there, the committed value stands.
+if [ "$mode" = "head" ] && [ "$branchon" = "rc" ]; then
+    trunkversion="$current_version"
+fi
+
 drifted=false
 [ "$trunkversion" != "$current_version" ] && drifted=true
 # dev-branch and stable deliberately carry no FOG_CHANNEL line at all (a
@@ -94,17 +117,26 @@ drifted=false
 if { [ -n "$current_channel" ] && [ "$channel" != "$current_channel" ]; }; then
     drifted=true
 fi
-if [ "$local" -eq 1 ]; then
+if [ "$mode" = "1" ]; then
     drifted=true
 fi
 
-if [ "$drifted" = true ] || [ "$local" -eq 1 ]; then
+# head mode stops here. Every other mode answers "what should the NEXT
+# commit say"; head answers "what should the commit that already exists
+# say", so adding 1 for a commit nobody is writing would defeat the whole
+# point of it.
+if [ "$mode" != "head" ] && [ "$drifted" = true ]; then
     # What's committed disagrees, so whatever calls this script is about
     # to add one more real commit to this branch to fix it. Recompute with
     # gitcount+1 - the count that will actually be true once that commit
     # exists - so the fix is correct the instant it lands instead of being
     # wrong by exactly the commit that made it. Without this, the very next
     # check finds "drift" again and fixes it again, forever.
+    #
+    # This is also why mode=1 lands one too high on an --amend: an amend
+    # REPLACES HEAD rather than extending it, so the +1 counts a commit that
+    # will never exist. That was the standing hazard of stamping a version
+    # from a local hook, and is one of the reasons no local hook does it now.
     compute_version "$((gitcount + 1))"
 fi
 

.githooks/pre-commit

@@ -57,22 +57,48 @@ updateLanguage
 psrfix
 
 
+# FOG_VERSION IS NOT STAMPED HERE ANY MORE. That is deliberate.
+#
+# The version is `git rev-list master..HEAD --count` put through
+# .githooks/lib/fog-version.sh -- a function of the commit graph. Stamping it
+# into a tracked line of packages/web/lib/fog/system.class.php on every commit
+# meant that any two branches open at once wrote DIFFERENT values to the SAME
+# line, so merging the base back into either one conflicted, every time, by
+# construction. Not a race: there is no ordering of commits that avoids it.
+#
+# It is also what left a dangling staged system.class.php bump behind after a
+# commit, which this branch's CLAUDE.md used to have to warn about.
+#
+# The version is now written in exactly one place -- on the base branch, after
+# a merge, by .github/workflows/sync-generated-files.yml -- where there is only
+# ever one writer and so nothing to conflict with. fog-workflows' daily sweep
+# still covers direct pushes and rc-*/feature-* branches.
+#
+# The consequence, stated so it is not rediscovered as a bug: a commit made
+# locally leaves FOG_VERSION reading whatever the last merge into the base
+# branch set. It is BEHIND on a feature branch, on purpose. Do not "fix" that
+# by putting the stamp back; a version that is a few commits stale costs a
+# wrong number in a build string, and stamping it per-commit costs a
+# hand-resolved conflict on every open pull request every time anything
+# merges.
+#
+# .githooks/pre-push, which refused a push whose committed version disagreed
+# with the branch, was removed in the same change: with nothing stamping a
+# version there is nothing for it to guard, and it would have blocked every
+# push instead.
+#
+# Ported from working-1.6 (GH-1510), where the bug was diagnosed.
 
-# Define the path to the system file
-system_file="$project_dir/packages/web/lib/fog/system.class.php"
-
-# Recompute FOG_VERSION/FOG_CHANNEL for the current branch. The formula is
-# shared with fog-workflows' CI check (see .githooks/lib/fog-version.sh) so
-# a local commit and CI's periodic sweep never compute two different
-# answers for the same branch state.
-gitbranch=$(git branch --show-current)
-fog_version=$(sh "$project_dir/.githooks/lib/fog-version.sh" $gitbranch 1)
-if [ "$(printf '%s\n' "$fog_version" | sed -n '3p')" = "true" ]; then
-    sh "$project_dir/.githooks/lib/apply-fog-version.sh" \
-        "$(printf '%s\n' "$fog_version" | sed -n '1p')" \
-        "$(printf '%s\n' "$fog_version" | sed -n '2p')"
-
-    # Add the modified system file to the staging area
-    git add "$system_file"
-fi
-
+# GH-1581: the hook's exit status is the status of the last command, which was
+# psrfix -- and psrfix returns 1 when php-cs-fixer is not installed, via
+# require_tools. So a machine without the optional tools printed "the commit
+# will proceed WITHOUT those changes" and then blocked the commit, with git
+# exiting 1 and saying nothing.
+#
+# Every step above is deliberately advisory: require_tools exists so a missing
+# formatter is a skip, not a failure, and CI regenerates all of it. Nothing in
+# this hook is a gate. Say so explicitly rather than leaving the status to
+# whichever helper happens to run last -- post-commit already ends this way.
+#
+# Ported from working-1.6, where it was diagnosed and fixed first.
+exit 0

.github/workflows/sync-generated-files.yml

@@ -0,0 +1,94 @@
+name: Sync generated files and version
+
+# Merge-triggered trigger stub. All the logic lives in FOGProject/fog-workflows'
+# update-lang-fix-psr-and-sync-version.yml; this file exists only because GitHub
+# Actions has no cross-repo merge trigger, so something has to live here to react
+# to a merge.
+#
+# THIS IS THE ONLY THING THAT WRITES FOG_VERSION ON A MERGE, and since GH-1510
+# it is the only thing that writes it on this branch at all outside the daily
+# sweep. .githooks/pre-commit used to stamp a version on every local commit;
+# that made every branch open at the same time hold a different value on the
+# same tracked line, so each merge left the others with a hand-resolved
+# conflict on system.class.php. Its header has the full reasoning.
+#
+# A client-side hook could not have covered this case anyway: a PR merged
+# through GitHub's web UI (squash, merge commit or rebase) runs no local hook,
+# so FOG_VERSION would go stale until the daily sweep fires at 10:10 UTC. This
+# closes that window.
+#
+# WHY `pull_request`, AND NOT `pull_request_target`
+#
+# `pull_request_target` looks like the right answer -- it is the variant that
+# gets secrets on fork PRs -- and the first version of this file used it. It
+# never fired once. GitHub reads a `pull_request_target` workflow from the
+# repository's DEFAULT branch (`stable` here), not from the PR's base branch, so
+# a copy living on working-1.6 and dev-branch is simply never consulted: the
+# workflow did not even appear in the Actions list, and four PRs merged into
+# working-1.6 without it running.
+#
+# `pull_request` is read from the base branch instead, so this file works where
+# it actually lives. Do not "fix" it back to `pull_request_target` without also
+# putting the file on `stable` -- and note that then only stable's copy would
+# execute, which makes editing the version on this branch a no-op.
+#
+# WHY NOT `push`
+#
+# That distinction is the whole safety argument, not caution. The sweep pushes
+# its fixup commit straight to the branch, and a direct push is not a PR merge,
+# so it cannot re-fire this stub. The 2026-07-28 runaway that put ~30 commits on
+# dev-branch in about 20 minutes was a push-triggered stub doing exactly that.
+# The schedule in fog-workflows stays exactly as it is, and remains the backstop
+# for direct pushes and for rc-*/feature-* branches.
+#
+# WHY THE SAME-REPO GUARD
+#
+# `pull_request` withholds secrets from fork PRs, and the reusable workflow needs
+# FOG_WORKFLOWS_PRIVATE_KEY to mint its App token -- so on a fork PR it would
+# fail rather than work. Skipping is right: a merged fork PR is picked up by the
+# daily sweep, exactly as a direct push already is. Better a gap the schedule
+# already covers than a red X on every external contribution.
+#
+# One file, identical on every branch that carries it, for the same reason
+# tests.yml is: fixing it should not mean editing it on three branches. Each
+# branch's copy only ever acts on merges into that branch, and the allowlist
+# below is what scopes it.
+
+on:
+  pull_request:
+    types: [closed]
+
+concurrency:
+  group: fog-sync-on-merge-${{ github.event.pull_request.base.ref }}
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    # An allowlist, not "not stable". Branches cut from working-1.6 inherit this
+    # file, and an rc-*/feature-* branch must NOT be merge-synced: fog-version.sh
+    # reports drift on every run for rc (it increments off the committed suffix
+    # rather than a commit count), so a per-merge sync would bump the RC suffix
+    # on every merge. Those stay on the daily sweep. stable is excluded because
+    # its version is owned entirely by fog-workflows' stable-releases.yml.
+    #
+    # `closed` fires on abandoned PRs too, hence the merged check -- and the
+    # reusable workflow uses its `branch` input verbatim, with no validation
+    # against its own watched list, so constraining it is this file's job.
+    if: >-
+      github.event.pull_request.merged == true
+      && github.event.pull_request.head.repo.full_name == github.repository
+      && contains(fromJson('["working-1.6", "dev-branch"]'), github.event.pull_request.base.ref)
+
+    # Least privilege, stated rather than inherited. Everything the reusable
+    # workflow writes -- the commit, the push, and the version badge -- uses a
+    # GitHub App token, so nothing on this path needs a writable GITHUB_TOKEN. A
+    # called workflow can never hold more permission than its caller, so leaving
+    # this to the repo-wide default would make the effective permission whatever
+    # that happens to be. See fos' create_release.yml for the same reasoning.
+    permissions:
+      contents: read
+
+    uses: FOGProject/fog-workflows/.github/workflows/update-lang-fix-psr-and-sync-version.yml@main
+    with:
+      branch: ${{ github.event.pull_request.base.ref }}
+    secrets: inherit

.github/workflows/tests.yml

@@ -0,0 +1,23 @@
+name: Tests
+
+# A pull_request trigger can only fire from the repository the PR is opened
+# against, so this stub has to live here even though every other fogproject
+# workflow lives in FOGProject/fog-workflows. It is deliberately six lines:
+# all of the logic is in the reusable workflow, so fixing the runner does not
+# mean editing this file on three branches.
+#
+# For pull_request events GitHub reads workflows from the merge of head into
+# base, so one copy on each BASE branch (working-1.6, dev-branch, stable)
+# covers every PR opened against it -- the contributor's branch needs
+# nothing.
+#
+# Not a push trigger, and not because of caution: the runaway that put ~30
+# commits on dev-branch in 20 minutes happened because the triggered
+# workflow pushed a commit back here. This one only reads.
+
+on:
+  pull_request:
+
+jobs:
+  suite:
+    uses: FOGProject/fog-workflows/.github/workflows/fogproject-tests.yml@main

CLAUDE.md

@@ -204,11 +204,29 @@ self::$HookManager->processEvent('EVENT_NAME', array('data' => &$data));
 
 ## Pre-commit hook (IMPORTANT — explains "files I didn't touch" in commits)
 
-`core.hooksPath` is `.githooks/`, so `.githooks/pre-commit` runs on **every** `git commit` (and `pre-merge-commit` delegates to it). It auto-modifies and `git add`s files beyond what you staged — this is expected, not a bug. Do **not** revert these. It does three things:
+`core.hooksPath` is `.githooks/`, so `.githooks/pre-commit` runs on **every** `git commit` (and `pre-merge-commit` delegates to it). It auto-modifies and `git add`s files beyond what you staged — this is expected, not a bug. Do **not** revert these. It does two things:
 
 1. **`updateLanguage()`** — regenerates `management/languages/messages.pot` via `xgettext`, sorts with `msgcat`, then `msgmerge`-updates every `.po`. Adds the whole `languages/` dir. Skipped if those tools aren't installed.
 2. **`psrfix()`** — runs `php-cs-fixer fix packages/web --rules=@PSR2` and **`git add packages/web`** unconditionally. Two consequences: your code may be auto-reformatted to PSR-2, and **any other dirty file under `packages/web/` gets swept into your commit** regardless of what you staged. Commit files outside `packages/web/` (like this `CLAUDE.md`) separately if you need them isolated.
-3. **Version bump** — derives a version from the branch name + commit count and rewrites `FOG_VERSION`/`FOG_CHANNEL` in `packages/web/lib/fog/system.class.php`. On `dev`/`stable` branches the channel is `Patches`. This step also tends to leave a **dangling staged `system.class.php`** bump after the commit; discard it with `git checkout -- packages/web/lib/fog/system.class.php` if you don't want it in the next commit.
+It used to do a third — a **version bump**, rewriting `FOG_VERSION`/`FOG_CHANNEL` in `packages/web/lib/fog/system.class.php` from the branch name and the commit count, which is also what left a **dangling staged `system.class.php`** behind after every commit. That was removed, along with `.githooks/pre-push` (which existed only to refuse a push whose committed version had drifted).
+
+### Why `FOG_VERSION` is not written on a branch
+
+`FOG_VERSION` is `git rev-list master..HEAD --count` — a property of the commit
+graph — but it is *stored* on a single tracked line of
+`packages/web/lib/fog/system.class.php`. Writing it per-commit made every branch
+open at the same time hold a **different value on the same line**, so each merge
+left the others with a hand-resolved conflict on `system.class.php` before they
+could be updated and re-tested. That is structural, not a race.
+
+The version now has exactly one writer: `.github/workflows/sync-generated-files.yml`,
+on the base branch, after a merge — plus fog-workflows' daily sweep for direct
+pushes and `rc-*`/`feature-*` branches. A feature branch's `FOG_VERSION` is
+*behind* while it is open, on purpose. The channel is `Patches` on
+`dev`/`stable`.
+
+Diagnosed on `working-1.6` in GH-1510; this branch has the same defect and takes
+the same fix.
 
 ---