Skip to content

Support Pre‑release Versioning #1380

Open

Description

@anagno

Is there an existing issue or pull request for this?

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

Activity

  1. welcome commented on Feb 24, 2026

    @welcome

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

  2. removed their assignment
    on Feb 25, 2026
  3. orhun commented on Feb 25, 2026

    @orhun
    Owner

    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?
  4. anagno commented on Feb 25, 2026

    @anagno
    Author

    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
  5. anagno commented on Feb 25, 2026

    @anagno
    Author

    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?

  6. ognis1205 commented on Feb 25, 2026

    @ognis1205
    Contributor

    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:

    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.

  7. anagno commented on Feb 25, 2026

    @anagno
    Author

    @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.

  8. ognis1205 commented on Feb 25, 2026

    @ognis1205
    Contributor

    @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:

    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.

  9. ognis1205 commented on Feb 25, 2026

    @ognis1205
    Contributor

    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.

  10. ognis1205 commented on Feb 25, 2026

    @ognis1205
    Contributor

    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 ?

  11. ognis1205 commented on Feb 25, 2026

    @ognis1205
    Contributor

    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.

  12. ognis1205 commented on Mar 10, 2026

    @ognis1205
    Contributor

    Sorry for the slow progress here. I'll take another look at the proposal again. My current feeling is that we should try to keep the solution and semantics as simple as possible.

  13. 17 remaining items

  14. Cyclonit commented on Apr 14, 2026

    @Cyclonit
    Contributor

    So, I took my time reading through all of the comments and to be frank, I think we are in an area of overcomplicating a solution to a problem that doesn't really exist. @anagno's initial proposal was simple and clean. Just introduce a pre-release tag and only consider tags that do match a simple pattern of <semver>-<pre-release tag>.<sequence nr>. If people want to embed even more information in their version numbers (which I would strongly advocate against), they simple leave the realm of what can reasonably be supported without over-complicating the situation.

    Also, I didn't go through the exercise of creating tables myself, but they feel like you just went through all possible permutations of tags and parameters and are trying to make sense of them. But that doesn't work. We need to think about the workflows that drive use of git-cliff and result in a much more limited set of reasonable combinations of parameters. And all of those make sense to me. The only question is whether git-cliff should spent effort on detecting unreasonable combinations and hold the user's hand or whether we enter undefined behaviour.

    I would go integrate the simple schema proposed here. It allows using git-cliff for versioning in a slightly more elaborate setup than the tool can support until now, without causing a mess.

  15. anagno commented on Apr 17, 2026

    @anagno
    Author

    @orhun @ognis1205 The #1345 is implementing the simpler logic. I would suggest either to take a look on the PR or if it is not something that you would like to support let`s close the PR

  16. added this to the 2.14.0 milestone on Apr 25, 2026
  17. orhun commented on Apr 25, 2026

    @orhun
    Owner

    Going to come back to this for 2.14.0

  18. modified the milestones: 2.14.0, 2.15.0 on Aug 22, 2026
  19. harlequin commented on Sep 10, 2026

    @harlequin

    I have read that this topic is moved into the 2.15.0 milestone. Do you have an estimation when it will be ready?

  20. orhun commented on Sep 18, 2026

    @orhun
    Owner

    I'm not sure... we need to either rebase #1345 or come up with another approach.
    I think that PR is a good start though.
    WDYT? Does that satisfy your use case?

  21. harlequin commented on Sep 19, 2026

    @harlequin

    Yes, this would be brilliant. If you would generate a preview version (a release candidate 😁) I can test it.

  22. Illustar0 commented on Sep 19, 2026

    @Illustar0

    For my use case, #1345 already meets my needs. Perhaps we could simply rebase that PR?
    I'd also be happy to test a preview release!

  23. anagno commented on Sep 22, 2026

    @anagno
    Author

    I rebased the PR, so whoever wants can give it a try

  24. Illustar0 commented on Sep 23, 2026

    @Illustar0

    I built the rebased PR and gave it a try — it works great!

    The PR description seems a little outdated now, though. For example, the option is currently --prerelease rather than --pre-release, and it needs to be used together with --bump.

    Other than that, it works very well for my use case. Thanks for rebasing it!

  25. anagno commented on Oct 20, 2026

    @anagno
    Author

    @harlequin @orhun Any input/suggestions for the open PR ?

  26. harlequin commented on Oct 28, 2026

    @harlequin

    Perfekt, please merge

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

Metadata

Metadata

Assignees

Labels

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions