Skip to content

feat: make the release tag and release name formats configurable - #24

Merged
philasmar merged 1 commit into
devfrom
asmarp/configurable-tag-format
Sep 2, 2026
Merged

philasmar merged 1 commit into
devfrom
asmarp/configurable-tag-format

Conversation

@philasmar

Copy link
Copy Markdown
Owner

Why

AutoVer tags a release by date (release_2026-09-02). That works when the tag is
just a marker, but it can't tell a consumer whether adopting a release will break
them. A repository whose releases are consumed by reference - a shared CI
templates repo pinned as ref: v1.4.0, for instance - needs the tag itself to
carry the version.

This makes the tag and release name formats configurable, so a release can be
identified by version instead of only by date.

What

{
  "TagFormat": "v{major}.{minor}.{patch}[-{prerelease}]"
}

Placeholders for the version components, prerelease label, date parts and
iteration, with [...] optional groups that render only when what's inside them
has a value - which is how one format covers both v1.4.0 and v1.4.0-beta.1,
or both release_2026-09-02 and release_2026-09-02_2.

ReleaseNameFormat is optional and follows TagFormat's family, so setting only
TagFormat is enough.

Defaults are unchanged. A repository that sets neither option keeps tagging
and naming releases exactly as before.

A tag is read back, not just written

AutoVer uses tag history to work out which release was most recent, and from that
the commit range a changelog covers. So a format has to be invertible, and the
rules enforce that when the configuration is read rather than part-way through a
release:

  • one family per format (version or date, never mixed - the two orderings
    disagree on a backport)
  • a complete ordering key (all of major/minor/patch, or a full date)
  • no ambiguous layouts - a format has to read back what it renders, checked by
    actually rendering a probe and parsing it, rather than by enumerating the ways a
    format can be ambiguous
  • a name git will accept, validated against git's own ref grammar before any
    project file is written, since the release commit is created before the tag

Fixes found along the way

  • Prerelease ordering now follows SemVer 2.0.0 precedence. Previously an
    ordinal string compare put beta.10 below beta.2, and 1.4.0 below
    1.4.0-beta.1. This backed GetNextMaxVersion, so it could pick the wrong
    "highest" version.
  • A hyphenated prerelease label such as 1.0.0-alpha-1 was dropped entirely
    when parsing, because the split required exactly two parts. A version-based tag
    renders from that parse, so the label would have been lost from the tag name.
  • The release name fell through to a tag-shaped string (release_2026-09-02
    instead of Release 2026-09-02) on the first release of a new date. Only the
    no-prior-tags and same-date paths had coverage, so this had gone unnoticed.
  • The current release is now the nearest release tag reachable from HEAD
    rather than the highest-ordering one. These differ after a backport, and
    autover changelog commits the CHANGELOG itself - moving HEAD off the tagged
    commit before the name and tag are read back for the release.

Docs

The README is reworked for GA: the "not ready for use beyond experimentation"
notice is gone, and it gains an install section, a getting-started walkthrough, a
commands reference, a configuration reference, and Dockerfile support (previously
undocumented). Also documents migrating an existing repository, including the two
things that bite: commit the autover.json change before releasing (changelog
loads config as of the release tag), and bridge the range boundary if you use a
commits-based changelog.

Testing

189 unit and 82 integration tests pass. New coverage includes the release
branch/merge-commit topology, the Dockerfile path, format migration in both
changelog modes, and failure cases asserting nothing is committed and no file is
modified when a format is rejected.

@philasmar
philasmar force-pushed the asmarp/configurable-tag-format branch from 6b7dd00 to 7acc30c Compare September 2, 2026 20:31
@philasmar
philasmar merged commit c7552b8 into dev Sep 2, 2026
2 checks passed
@philasmar
philasmar deleted the asmarp/configurable-tag-format branch September 2, 2026 20:36
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.

1 participant