maxpeterkaya/changelog
Watch
1
0
Fork
You've already forked changelog
 0
Code Issues 1 Pull requests 2 Projects Releases 21 Packages 1 Wiki Activity Actions
Page: Tag Ranges and Rollup
Pages
Home Inputs Reference Installation Outputs and Commit Groups Styles and LLM Providers Tag Ranges and Rollup Troubleshooting Writing Changelogs to the Repository
1 Tag Ranges and Rollup
maxpeterkaya edited this page 2026-09-16 10:11:05 -04:00
Table of contents

Tag Ranges and Rollup

The changelog is built from the commits between two tags: a from tag (start of the range) and a to tag (end of the range, the release being described).

Default range

Without tag, to_tag, and from_tag, the two most recent tags are used:

  • to = the newest tag.
  • from = the tag immediately before it.

If the repository has only one tag, there is no from tag, so the changelog is built from every commit up to that tag. This is expected for a first release.

Choosing tags explicitly

Input Effect
tag Generate the changelog for this tag.
to_tag End tag of the comparison range.
from_tag Start tag of the comparison range.

When none of these are set, the newest tag is used as the end of the range.

Rollup

By default the range is always the newest tag compared against the tag before it. For a minor or major release this can hide changes that shipped in earlier patch releases of the same series.

Set rollup: true to widen the range by semantic version:

  • A patch release (v3.2.12 after v3.2.11) still compares against the previous tag.
  • A minor release (v3.3.0) compares against the start of the previous minor series (v3.2.0), so every v3.2.x change is included.
  • A major release (v4.0.0) compares against the start of the previous major series (v3.0.0), so every v3.x change is included.
  • Tags with a v prefix and tags without one are both accepted.
  • Pre-release tags resolve to their core version, so v3.2.0-rc1 is treated as v3.2.0.

Examples

Given these tags, newest first:

Tags Rollup From To Why
v3.3.0, v3.2.11, v3.2.0, v3.1.0 off v3.2.11 v3.3.0 Previous tag only.
v3.2.12, v3.2.11, v3.2.0 on v3.2.11 v3.2.12 Patch release keeps the previous tag.
v3.3.0, v3.2.11, v3.2.0, v3.1.0 on v3.2.0 v3.3.0 Minor release rolls to the previous minor series start.
v4.0.0, v3.2.11, v3.2.0, v3.0.0 on v3.0.0 v4.0.0 Major release rolls to the previous major series start.

Fallbacks

Rollup is best-effort. It falls back to the previous tag, with a warning, when:

  • the base tag does not exist in the repository (for example v3.2.0 was never tagged);
  • the newest or previous tag is not valid semantic versioning;
  • the release is a patch release, so there is no wider range to roll up.

For a repository with tags v3.3.0, v3.2.11, v3.1.0 and rollup: true, the base tag v3.2.0 is missing, so the range falls back to v3.2.11.

Home · Installation · Inputs Reference · Outputs and Commit Groups · Writing Changelogs to the Repository · Styles and LLM Providers · Troubleshooting