Support Pre‑release Versioning

[anagno]

Is there an existing issue or pull request for this?

• feat(args): add the pre-release option #1345

Feature description

Add first‑class support for producing pre‑release versions (e.g., alpha, beta, rc) when computing the next version in git-cliff. Many teams ship pre‑release builds to internal users or early adopters prior to a final release. Today, git-cliff can compute and bump versions, but there’s no explicit mechanism to mark the next version as a pre‑release and increment the pre‑release sequence.

Desired solution

The introduction of a new CLI flag that will instruct git-cliff to incremental the version and at the same time use pre-relase versioning. Something similar to the logic used in the the commit-and-tag-version project

Examples of usage:

git cliff --bumped-version --pre-release
git cliff --bumped-version --pre-release rc
git cliff --bumped-version --bump major --pre-release alpha
git cliff --bump minor --pre-release beta
git cliff --bump --pre-release beta

Semantics

• If no existing pre‑release on the next version:
  • Set pre‑release to .0 (e.g., alpha.0, beta.0, rc.0).
• If there is an existing pre‑release:
  • if the same type: increment the numeric suffix (rc.1 to rc.2).
  • If a different type: set to the new type with numeric suffix .0. (as long as we are not reducing the type of the release. For example if we already have beta.1 and the user specifies alpha, then the resulting version should be beta.2 and not alpha.0)

Furthermore, prereleases are also usually filtered out, so the implementation should also be able to handle the skip_tags options and still calculate correct the next version.

Alternatives considered

I did not find a way on the documentation to achieve the creation of preleases, without creating first the tag myself.

Additional context

Continuation of the discussion from #1345

[welcome]

Thanks for opening your first issue at git-cliff! Be sure to follow the issue template! ⛰️

[orhun]

This sounds reasonable. However there are still some cases to think about:

Current Tag(s)	Command	Notes
(none)	--bump --pre-release alpha	Should produce <initial_tag>-alpha.0, right? But what if e.g. <initial_tag> is 0.1.0-alpha.5
1.2.0-beta.2	--bump --pre-release beta	1.2.0-beta.3 or 1.2.1-beta.0?
1.2.0-rc.3	--bump	Should probably produce 1.2.0 instead of 1.2.1, right?
1.2.0-alpha.2	--pre-release beta	Should this become 1.2.0-beta.0?
1.2.0-beta.3	--pre-release alpha	Downgrade to alpha OR ignore and produce 1.2.0-beta.4?
1.2.0-rc.0, 1.2.0-rc.2	--pre-release rc	Should this become 1.2.0-rc.3 or fill gap with rc.1?
1.2.0-beta.2+build.45	--pre-release beta	Should build metadata be preserved, stripped, or ignored?
1.2.0-alpha.1.2	--pre-release alpha	Is this valid?
v1.2.0	--pre-release beta	Should this produce v1.3.0-beta.0 (preserve prefix?)
1.2.0-beta.3 (skipped via skip_tags)	--pre-release beta	Should skipped prereleases still affect version calculation?
0.3.0-beta.2	--bump major --pre-release alpha	0.4.0-alpha.0 or 1.0.0-alpha.0?
1.2.0-beta.2, 1.2.0	--pre-release rc	Start 1.3.0-rc.0 or reuse 1.2.0?

[anagno]

I would say:

Current Tag(s)	Command	Notes
(none)	--bump --pre-release alpha	I would ignore the flag. The semantics are not clear. I would not apply the flag in cases where we do not have already a release. If the user wants an alpha initial tag, he/she can specify it directly in the options
1.2.0-beta.2	--bump --pre-release beta	1.2.0-beta.3. This helps with pipelines or instructions. You know from the beggining that the counting will be correct
1.2.0-rc.3	--bump	Should produce 1.2.0 . This is the point of release candidates, right? To be able to release the final version without bumping patch or minor version
1.2.0-alpha.2	--pre-release beta	Should become 1.2.0-beta.0. beta is greater than alpha, so we can just start counting from 0
1.2.0-beta.3	--pre-release alpha	Ignore and produce 1.2.0-beta.4. Or if not possible just reject it and warn the user for the mistake ?
1.2.0-rc.0, 1.2.0-rc.2	--pre-release rc	I would argue that it should be rc.3. I am guessing the same behavior with existing normal released tags. We increment the last valid one.
1.2.0-beta.2+build.45	--pre-release beta	That`s a good question. For this complicated cases I would argue that probably we should leave it to the user. But how can we let the user input the parameters? Probably we need better input arguments in the CLI ?
1.2.0-alpha.1.2	--pre-release alpha	What does it even mean? Probably next_version would increase the last digit ... I would reject to be honest, but I do not know what the user is trying to achieve. Probably the same use case as the previous one
v1.2.0	--pre-release beta	I am guessing it should preserve the prefix and produce v1.3.0-beta.0. What happens to the normal tags ? I would keep the same behavior, as the normal tags
1.2.0-beta.3 (skipped via skip_tags)	--pre-release beta	I would say yes, it should be taken into consideration and affect the version calculation. If the user really wants to exclude it, he/she can use the ignore_tags. That way you can also put the pre-release tags in the ignore_tags and then they will be concantanated into the next release
0.3.0-beta.2	--bump major --pre-release alpha	What would happen if we just had 0.3.0 with --bump major? If it the result is 0.4.0, then we increment to 0.3.0-beta.3 (because the 0.3.0-beta.2 --bump major should produce 0.3.0 ). If the result is 1.0.0, then we can start with 1.0.0-alpha.0.
1.2.0-beta.2, 1.2.0	--pre-release rc	Next valid version with -rc appended. So 1.3.0-rc.0

[anagno]

One more comment for the 1.2.0-beta.2+build.45 use case. Apparently it is specified in the specs: Build metadata MUST be ignored when determining version precedence. So after that I would say it should be ignored/preserved. So something like 1.2.0-beta.3+build.45 . What does git-cliff currently does with build metadata?

[ognis1205]

I think the interaction between --bump and --prerelease will likely require quite a bit of design discussion, and it's not entirely clear yet whether (or how) we want to support all those edge cases.

As a first step, I would suggest starting with a smaller and more well-scoped change: extending the existing --bump option to support prerelease as a version type, similar to the current major, minor, and patch options:

• https://git-cliff.org/docs/usage/bump-version#bump-to-a-specific-version-type

This would likely require clarifying some details around next_version, but overall the semantics seem much less ambiguous compared to introducing a separate --prerelease flag and defining its interaction with --bump.

Once that is in place, we could then iterate on more advanced prerelease workflows if needed.

[anagno]

@ognis1205 Would something similar to your comment be ok ?

#[derive(Parser)]
struct Cli {
    #[arg(long, value_enum)]
    bump: Option<BumpOption>,

    #[arg(long, required_if_eq("bump", "prerelease"))]
    prerelease: Option<String>,
}

For pre-releases we will need the type, so it has to specified.

[ognis1205]

@anagno

The implementation sketch you shared is about handling the dependency between --bump and --prerelease. What I am proposing here is slightly different. I'm focusing on adding Prerelease as a new variant to BumpType:

git-cliff/git-cliff-core/src/config.rs

Lines 311 to 318 in e7e89c4

	pub enum BumpType {
	/// Bump major version.
	Major,
	/// Bump minor version.
	Minor,
	/// Bump patch version.
	Patch,
	}

Since we already rely on the next_version crate, which extends semver::Version and provides prerelease support via the NextVersion trait, we can leverage that implementation directly:

https://docs.rs/next_version/0.3.1/next_version/trait.NextVersion.html

My idea is:

• Add prerelease as a valid value to --bump
• Do not introduce or fully support --prerelease yet
• If prerelease bump is requested but no prerelease identifier is detected in the previous version, return an error during changelog generation

This way, we can introduce --bump prerelease in a minimal and well-scoped manner without blocking on the full --prerelease CLI design. Then, the detailed behavior and interaction between --bump and --prerelease can continue to be discussed in this tracking issue.

[ognis1205]

I think we should first define what --bump prerelease means in isolation, before defining how it interacts with other flags or edge cases.

That said, even the semantics of --bump prerelease itself might turn out to be more complex than it initially appears. A prerelease is technically not a version "level" like major/minor/patch, but rather an identifier attached to a version. Because of that, modeling it as a --bump type could introduce some conceptual distortion in the design and it might not even be the best abstraction for this feature.

As we can already see from the combination tables discussed here, the number of cases this feature would need to cover is larger than it might seem at first glance. So it may be worth carefully scoping what we want the initial behavior to guarantee before expanding it to handle all edge cases.

[ognis1205]

Alternatives considered

I did not find a way on the documentation to achieve the creation of preleases, without creating first the tag myself.

I'm curious how this has been handled in practice so far.
For example, in @ratatui , how were prerelease changelog managed @orhun ?

[ognis1205]

Ah, I took another look at the current implementation, and it seems that the existing --bump behavior already covers what I was trying to propose here (--bump prerelease).

So there's no need to introduce Prerelease as a new BumpType after all. Sorry for the noise, please disregard this suggestion.