Document the commit-subject convention for version.gradle.kts - #41
Conversation
Every commit touching the root `version.gradle.kts` uses the subject "Bump version -> `<version>`" — even a syntax-only edit, such as the `by extra(...)` -> `extra.set(...)` migration, which repeats the unchanged current version. GitHub's tree view shows the last-touching commit's subject next to each file, so the convention keeps the current version of `master` readable straight from the file listing. `guidelines/version-policy.md` gains a section stating the rule, the rationale, and what reviewers must not flag for this file. `skills/bump-version/SKILL.md` is reconciled with the convention: "one bump per branch" and the step-7 validation now count commits that advance the version value, not commits merely reusing the subject. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Documents a team convention for commit subjects when editing the root version.gradle.kts, so GitHub’s tree view reliably shows the current version next to the file. Updates the bump-version skill documentation to align its “one bump per branch” guidance and validation steps with this convention.
Changes:
- Add a new “Commit messages for
version.gradle.kts” section to the version policy, including rationale and reviewer guidance. - Clarify in
bump-versionthat “one bump per branch” refers to version advancement, not uniqueness of theBump version ->subject. - Adjust the validation step to treat repeated bump-subject commits as potentially valid and to focus on counting version-advancing commits.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
guidelines/version-policy.md |
Defines the commit-subject convention for version.gradle.kts, plus rationale and reviewer expectations. |
skills/bump-version/SKILL.md |
Aligns the skill’s commit guidance and validation narrative with the new policy. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: db8873ee62
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Apply the `review-docs` findings from the pre-PR pass: add the colon before the subject example, absorb a widow and a runt, use restrictive "that", align the subject placeholder on `<version>` in both files, cite the policy section as a single code span, unify the tree-view phrasing, and use underscore italics per the file's own style. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (2)
skills/bump-version/SKILL.md:301
- With the new convention,
countis the number of commits that use the subject, so1is not inherently the expected/only correct value (a syntax-onlyversion.gradle.ktsedit can make it>1even with exactly one advancing commit). Update this bullet so it doesn’t implycount == 1is the expected baseline.
- **1** — expected. The branch carries exactly one bump.
skills/bump-version/SKILL.md:295
- The
countcalculation scans all branch commit subjects, so it can be inflated by unrelated commits that happen to reuse the same subject. Since this step is aboutversion.gradle.kts, scopegit logto commits that touched that file to avoid false positives.
# Count commits using the bump subject. `|| true` keeps the zero-match case
# (grep exits 1) from aborting under `set -e`.
count="$(git log --format=%s "origin/$BASE..HEAD" | grep -c '^Bump version ->' || true)"
What
Documents the team convention that every commit touching the root
version.gradle.ktsuses the subjectBump version -> `<version>`— even when the edit is syntax-only (e.g., migratingby extra(...)toextra.set(...)) and the version number does not change.guidelines/version-policy.md— new section Commit messages forversion.gradle.ktsstating the rule, the rationale, and explicit guidance that reviewers (human and agent) must not flag repeated bump subjects on one branch, or a subject "claiming" an already-happened bump, as findings for this file.skills/bump-version/SKILL.md— reconciles the skill with the convention:>1bump subjects as over-bumped outright; it now checks how many of the counted commits actually advance the version value, expecting exactly one.Why
GitHub's repository tree view shows, next to each file, the subject of the last commit that touched it. Keeping the bump-style subject "afloat" beside
version.gradle.ktslets anyone read the current version ofmasterstraight from the file listing, without opening the file. Product-owner decision (2026-08-05), after a review flagged a syntax-only migration commit as a "duplicate bump".Reviewer notes
spine-code-review/SKILL.mdneeds no change: it enumerates no commit-message checks (its version gate compares version values, not subjects). The only subject-count check in the skill set lived inbump-versionstep 7 and is fixed here../config/pullnext floats.agents/shared.review-docs: APPROVE WITH CHANGES — no Must-fix; four Should-fix prose points (colon before the fence, a widow, a runt, one restrictive "which") noted in the session for follow-up.🤖 Generated with Claude Code