Skip to content

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

Description

@lesnik512

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions