From 987250b60ab8e5c64b2c2a946071aa3ec9af407c Mon Sep 17 00:00:00 2001 From: Z8MB1E Date: Tue, 8 Sep 2026 12:18:43 -0400 Subject: [PATCH] docs: restrict release version bumps and tags to main deploys --- AGENTS.md | 2 +- DEPLOYMENT.md | 2 ++ README.md | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 20c15f7..a1469c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -362,7 +362,7 @@ shadcn/ui components live in `src/components/ui/`. Use `bunx shadcn@latest add < **Pre-deploy dash gate**: before any production build, release version bump, or deploy, run the `dash-sanitize` skill (`/home/jason/.agents/skills/dash-sanitize/SKILL.md`) and show its verification output (re-scan classification + filtered tsc) before proceeding. A dirty user-facing dash scan pauses the release; a clean re-scan on an already-swept tree takes seconds and should still be run rather than assumed. -**Version bump after git commands**: whenever a `/git` or `/git-master` workflow creates commits, also bump the patch version with `bun pm version patch --message "v%s - "` and push it together with the work. `` is a short comma-separated summary of what the release ships (derived from the commits just created), e.g. `v0.2.4 - add voicelines, update git rules` — never a bare version number. The command itself creates the `vX.Y.Z` version commit **and** a local git tag. `push.followTags` is set in this repo, so a plain `git push` automatically carries the annotated release tag with the commits — but never use a bare `git push --tags`, which sends only tags and not the branch. The deployed site's version overlay reads `package.json`'s `version` (Coolify builds have no git metadata, so the displayed version is `+`), and an unbumped semver means every deploy shows the same `0.2.0`-style number even though the commit-hash suffix changes. Skipping the bump — or pushing the commit without its tag — makes releases indistinguishable and breaks version history. +**Version bumps and release tags: `main` deploys only**: whenever a `/git` or `/git-master` workflow lands work on `main` (or a deploy is being cut), bump the version with `bun pm version patch --message "v%s - "` and push it together with the work. `` is a short comma-separated summary of what the release ships (derived from the commits just created), e.g. `v0.2.4 - add voicelines, update git rules` (never a bare version number). The command itself creates the `vX.Y.Z` version commit **and** a local git tag. `push.followTags` is set in this repo, so a plain `git push` automatically carries the annotated release tag with the commits, but never use a bare `git push --tags`, which sends only tags and not the branch. **Feature branches must never bump versions or push release tags**: parallel branches bumping the same semver line desync `package.json` from the tags that actually deploy, and at merge time the version history no longer matches what shipped. Release tags exist solely to mark `main` deploys. The deployed site's version overlay reads `package.json`'s `version` (Coolify builds have no git metadata, so the displayed version is `+`), and an unbumped semver means every deploy shows the same `0.2.0`-style number even though the commit-hash suffix changes. Skipping the bump on a `main` deploy (or pushing the deploy commit without its tag) makes releases indistinguishable and breaks version history. ## Gotchas diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 8e8166c..53281fc 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -208,6 +208,8 @@ Recommended flow: 4. Coolify waits for `/api/health` to come back 200, then routes traffic. 5. If a new migration shipped with that deploy, run it via `docker exec` or a Scheduled Task (Sec. 7). +> **Tags only from `main` deploys.** Create and push the `vX.Y.Z` release tag only when deploying from `main`. Never bump versions or push release tags from feature branches: parallel branches bumping the same semver line desync `package.json` from the tags that actually deploy, and at merge time the version history no longer matches what shipped. + > **Version metadata in builds.** The image build embeds git info into `src/generated/versionInfo.json` (shown in the admin VersionOverlay and on `/api/version`). Coolify **deletes `.git`** from the build context, so the build reads the commit SHA from the `SOURCE_COMMIT` build arg instead of `git` (see the Dockerfile's `ARG SOURCE_COMMIT` block). For that to work, enable **"Include Source Commit in Build"** under the application's *Advanced* settings (and leave "Inject Build Args to Dockerfile" on, which is the default) — otherwise the version overlay falls back to `version` only. > > **Commit metadata availability.** On Coolify builds, `SOURCE_COMMIT` is the commit SHA, but tags, dates, and subjects are not injected automatically. If the build environment provides `GIT_COMMIT_DATE` and `GIT_COMMIT_SUBJECT`, the generator records them as `lastUpdated` and `commitMessage`; otherwise `lastUpdated` falls back to the image build time and the commit message remains unavailable. The existing `canSeeCommit` permission still gates commit details in the overlay. diff --git a/README.md b/README.md index 409f517..efb8f4b 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ For an Arma 3 unit deployment we self-host on **Coolify** with one container per ### CI version bumps -Run `bun run version:bump -- --base "$CI_PREVIOUS_SHA" --head "$CI_SHA"` before the production build. The script bumps minor for product changes under `src/app`, `src/components/frontend`, `src/lib`, `src/collections`, `src/bot`, `src/hooks`, `src/migrations`, or `src/utils`, and patch for other deployable changes. Use `--dry-run` to inspect the decision. Commit the changed `package.json` back to the deployment branch (for example, with a `[skip ci]` commit if your CI provider supports it); the existing `generate:version-info` build step will publish the new version to the app. +Run `bun run version:bump -- --base "$CI_PREVIOUS_SHA" --head "$CI_SHA"` before the production build. The script bumps minor for product changes under `src/app`, `src/components/frontend`, `src/lib`, `src/collections`, `src/bot`, `src/hooks`, `src/migrations`, or `src/utils`, and patch for other deployable changes. Use `--dry-run` to inspect the decision. Commit the changed `package.json` back to the deployment branch (for example, with a `[skip ci]` commit if your CI provider supports it); the existing `generate:version-info` build step will publish the new version to the app. Version tags (`vX.Y.Z`) ship only on `main` deploys: never bump versions or push release tags from feature branches, because parallel bumps desync `package.json` from the tags that actually deploy. For the full setup — per-env Postgres provisioning, env vars, scheduled jobs, persistent media volume, SSE single-instance caveat, rollbacks, troubleshooting — see **[DEPLOYMENT.md](./DEPLOYMENT.md)**.