The published docs tell users that the conventional-commits strategy walks every commit since the
latest tag. It does not. SemvertagUseCase.__call__ fetches exactly one commit —
provider.get_latest_commit_on_default_branch() — and hands it to BumpStrategy.decide(commit).
There is no range fetch anywhere in semvertag/, and the Provider protocol has no operation that
could perform one.
Wrong today, on https://semvertag.modern-python.org:
docs/strategies/conventional-commits.md — the opening paragraph ("decides a per-commit bump. The
orchestrator combines per-commit bumps across the commit range and applies the highest one") and
the whole Commit scanning section, including its claim that one BREAKING CHANGE: anywhere in
the range forces a major, and its paragraph on how merge commits are scanned.
docs/providers/github.md and docs/providers/gitlab.md — the strategy table row "Bump from
Conventional Commits headers since the last tag", and the "semvertag scans commits since the last
tag and chooses the highest bump implied by their type prefixes" paragraph in each.
docs/strategies/branch-prefix.md — "that strategy scans every commit since the last tag and does
not depend on merge metadata".
The user-visible consequence is real: a team told that any feat: since the last tag yields a minor
will silently get no bump when the head commit happens to be a chore:, and nothing in the output
explains why.
Fixing the prose is the small half. The issue should first settle the product question the docs
imply an answer to: should conventional-commits scan a range? Scanning is what the convention
normally means, and it is what the docs promised, but it needs a new Provider operation
(list commits between two refs, on two independently versioned REST APIs) and it would change the
bump for existing users. Decide that, then either correct the four pages to describe the
head-commit-only behaviour or implement the range and correct them to match.
Note for whoever picks this up: the phrase to remove is "last tag" regardless of the outcome —
CONTEXT.md defines the baseline as latest tag, the highest by SemVer precedence, and rejects
"last tag" and "most recent tag" because both read as newest-by-date.
Revisit trigger: none — this is a live defect in published documentation and is actionable now.
Origin: the CONTEXT.md glossary audit during the planning/ migration. The synonym straggler was
fixable in that commit; the false claim wrapped around it was not.
The published docs tell users that the
conventional-commitsstrategy walks every commit since thelatest tag. It does not.
SemvertagUseCase.__call__fetches exactly one commit —provider.get_latest_commit_on_default_branch()— and hands it toBumpStrategy.decide(commit).There is no range fetch anywhere in
semvertag/, and theProviderprotocol has no operation thatcould perform one.
Wrong today, on https://semvertag.modern-python.org:
docs/strategies/conventional-commits.md— the opening paragraph ("decides a per-commit bump. Theorchestrator combines per-commit bumps across the commit range and applies the highest one") and
the whole Commit scanning section, including its claim that one
BREAKING CHANGE:anywhere inthe range forces a major, and its paragraph on how merge commits are scanned.
docs/providers/github.mdanddocs/providers/gitlab.md— the strategy table row "Bump fromConventional Commits headers since the last tag", and the "semvertag scans commits since the last
tag and chooses the highest bump implied by their type prefixes" paragraph in each.
docs/strategies/branch-prefix.md— "that strategy scans every commit since the last tag and doesnot depend on merge metadata".
The user-visible consequence is real: a team told that any
feat:since the last tag yields a minorwill silently get no bump when the head commit happens to be a
chore:, and nothing in the outputexplains why.
Fixing the prose is the small half. The issue should first settle the product question the docs
imply an answer to: should
conventional-commitsscan a range? Scanning is what the conventionnormally means, and it is what the docs promised, but it needs a new
Provideroperation(list commits between two refs, on two independently versioned REST APIs) and it would change the
bump for existing users. Decide that, then either correct the four pages to describe the
head-commit-only behaviour or implement the range and correct them to match.
Note for whoever picks this up: the phrase to remove is "last tag" regardless of the outcome —
CONTEXT.mddefines the baseline as latest tag, the highest by SemVer precedence, and rejects"last tag" and "most recent tag" because both read as newest-by-date.
Revisit trigger: none — this is a live defect in published documentation and is actionable now.
Origin: the
CONTEXT.mdglossary audit during theplanning/migration. The synonym straggler wasfixable in that commit; the false claim wrapped around it was not.