Skip to content

docs: describe the head-commit rule instead of a commit-range scan - #76

Merged
lesnik512 merged 2 commits into
mainfrom
docs/head-commit-only
Sep 19, 2026
Merged

lesnik512 merged 2 commits into
mainfrom
docs/head-commit-only

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Closes #57.

The conventional-commits strategy decides from the head commit alone: SemvertagUseCase fetches one commit and hands it to BumpStrategy.decide. Four pages said it scanned the commits since the latest tag. This settles the product question the issue raised in favour of keeping the head-commit rule, corrects the pages, and records the decision.

Decision

Head-commit-only stays. The action runs once per push, and with squash merges a push is one commit, so the range is the head. A merge-commit workflow is served by branch-prefix, which reads the merge commit that is the head. A range scan would need a new Provider operation on two REST APIs, a bound on long ranges, and would change existing users' bumps. docs/adr/0006-strategies-decide-from-the-head-commit-only.md records this; a range scan stays a possible opt-in if a merge-commit team using Conventional Commits asks.

Pages

  • docs/strategies/conventional-commits.md: opening paragraph and the former "Commit scanning" section, now "Head commit only": squash merges pair with this strategy, a merge-commit head declines with no_conforming_commit, branch-prefix is the alternative there but produces no majors, and a failed run must be re-run.
  • docs/strategies/branch-prefix.md: the cross-reference no longer claims a scan; a "Head commit only" paragraph carries the re-run note for this strategy too.
  • docs/providers/github.md, docs/providers/gitlab.md: strategy table rows, the strategy-choice section (branch-prefix needs a merge commit at the head; squash merges report no_merge_commit), and a Troubleshooting bullet for the never-tagged push.
  • "last tag" is gone from prose, per the glossary. BREAKING CHANGE: is described as a body footer, which is where conventional_commits.py reads it.

Glossary

CONTEXT.md gains Head commit with latest commit under Avoid, since latest tag already pins "latest" to mean highest by precedence. README.md, docs/index.md and both provider pages now say "head commit" where they said "latest commit". The provider method keeps its name.

Checks

pytest (481 passed), eof-fixer, lychee --offline --include-fragments over every touched page, and mkdocs build --strict. Reviewed on two axes before opening; the review's factual findings are in the second commit.

The conventional-commits strategy decides from the head commit alone;
four pages said it scanned the commits since the latest tag. Correct
them, pair each strategy with its merge style, note that a failed run
must be re-run, and record the decision as ADR 0006.
Review follow-ups: BREAKING CHANGE lives in the body, not the type
prefix; branch-prefix needs a merge commit at the head and produces no
majors; the re-run note reaches both provider troubleshooting lists and
the branch-prefix page; "head commit" enters the glossary and replaces
"latest commit" in prose.
@lesnik512
lesnik512 merged commit fbe3934 into main Sep 19, 2026
9 checks passed
@lesnik512
lesnik512 deleted the docs/head-commit-only branch September 19, 2026 17:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The docs describe a commit-range scan that semvertag does not do

1 participant