Skip to content

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

Open
anagno wants to merge 1 commit into
orhun:mainfrom
anagno:feat/pre-releases
Open

anagno wants to merge 1 commit into
orhun:mainfrom
anagno:feat/pre-releases

Conversation

@anagno

@anagno anagno commented Jan 16, 2026 •

Copy link
Copy Markdown

Add the possibility of specifying prereleases via the cli arguments. Now it is possible to specify in the cli --prerelease [type] and the bump version will be a prerelease

Description

Many projects have the need of creating pre-releases for testing with users, before the final release. This PR implements and extra cli argument that the user can specify the type of the prerelease and then changelogs for prereleases will be generated.

It makes sure that the calculation of the prerelease is correct. So if there already an rc version and the user specifies via the cli --pre-release alpha, then the calculcation will be correct and it will increment the rc version

There was a similar issue in the past, but it was never planned. So if it is not of interests feel free just to close the PR.

To make it work with ingore_tags I had to refactor a bit the process_releases function. Now it happens in 2 steps, so the calculation of the next version happens first, and then we filter out the releases that we do not want.

Motivation and Context

Give the possibility of specifying prereleases, so that projects can create changelogs for these releases

How Has This Been Tested?

I included a couple of new UTs and tested it manually by invonking the git-cliff cli. For example:

cargo run -- --bumped-version --bump --prerelease alpha
v2.12.0-rc.0

Screenshots / Logs (if applicable)

Types of Changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation (no code change)
  • Refactor (refactoring production code)
  • Other

Checklist:

I have not yet gone through all the points ( and I have not yet update the docs, because I wanted first to get some feedback :) )

  • My code follows the code style of this project.
  • I have updated the documentation accordingly.
  • I have formatted the code with rustfmt.
  • I checked the lints with clippy.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

@anagno
anagno requested a review from orhun as a code owner January 16, 2026 11:06
@welcome

welcome Bot commented Jan 16, 2026

Copy link
Copy Markdown

Thanks for opening this pull request! Please check out our contributing guidelines! ⛰️

@codecov-commenter

codecov-commenter commented Jan 16, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 79.64602% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 54.73%. Comparing base (344db94) to head (1e34280).
⚠️ Report is 2 commits behind head on main.

Files with missing lines Patch % Lines
git-cliff-core/src/changelog.rs 64.00% 18 Missing ⚠️
git-cliff/src/lib.rs 0.00% 4 Missing ⚠️
git-cliff-core/src/release.rs 98.28% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1345      +/-   ##
==========================================
+ Coverage   53.97%   54.73%   +0.77%     
==========================================
  Files          29       29              
  Lines        2676     2717      +41     
==========================================
+ Hits         1444     1487      +43     
+ Misses       1232     1230       -2     
Flag Coverage Δ
unit-tests 54.73% <79.65%> (+0.77%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@anagno
anagno force-pushed the feat/pre-releases branch 5 times, most recently from 930792c to a44bbc3 Compare January 21, 2026 12:33
@anagno

anagno commented Jan 30, 2026

Copy link
Copy Markdown
Author

@orhun Is this PR of interest, or should I close it?

@orhun

orhun commented Feb 21, 2026

Copy link
Copy Markdown
Owner

Hey, apologies for the delay. I'll get back to this soon :)

@ognis1205 ognis1205 left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for opening this PR and working on this @anagno !

I’m currently neutral about supporting pre-releases in some form.

One thing that comes to mind, though, is that Semantic Versioning does not define any specific format or naming convention for pre-release identifiers (see https://semver.org/#spec-item-9). While alpha / beta / rc are commonly used, they are still just conventions and not part of the specification.

Because of that, supporting only these specific identifiers (as proposed in this PR) might be somewhat limiting and not fully generic. If we decide to move forward with accepting this feature, I'd personally prefer a more flexible approach that allows arbitrary pre-release identifiers rather than restricting it to a predefined set, although I'm not entirely sure how feasible that would be within the current implementation.

Just my first-glance feedback. Curious to hear if others have thoughts or alternative ideas from @anagno on how we might approach this.

Would extending the existing --bump option to support pre-releases achieve a similar result? 🤔

@anagno

anagno commented Feb 23, 2026

Copy link
Copy Markdown
Author

I tried to follow a similar logic to the approach used in the the commit-and-tag-version project

Regarding generalization: we can extend the behavior, but we are still constrained by what the next_version crate supports, since that crate is responsible for computing the next version. I can make some more experiments, but I think it is feasible. Should it just accept any string and then pass it as parameter?

The decision not to use the existing --bump flag was intentional. My thinking was that a user might want to request both a major-level bump and a pre-release at the same time. In that case, combining everything into a single flag felt limiting, so I introduced a separate flag for pre-releases.

@anagno
anagno marked this pull request as draft February 23, 2026 13:08
@anagno

anagno commented Feb 23, 2026

Copy link
Copy Markdown
Author

I pushed a commit that generalizes the implementation. If no pre-release type is provided via the CLI, alpha is used as the default, due to limitations in the next_version crate.

@anagno
anagno marked this pull request as ready for review February 23, 2026 13:23

@ognis1205 ognis1205 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to follow a similar logic to the approach used in the the commit-and-tag-version project

Thanks for explaining the rationale. That helps a lot. I understand the background and why you chose to follow that approach.

Regarding generalization: we can extend the behavior, but we are still constrained by what the next_version crate supports, since that crate is responsible for computing the next version. I can make some more experiments, but I think it is feasible. Should it just accept any string and then pass it as parameter?

next_version already supports prerelease increments, although the incrementing behavior is defined by its own rules. Since there isn't a strict specification governing prerelease value semantics or how they should be incremented, we would inevitably be choosing one interpretation anyway.

Given that, and to keep responsibilities clearly separated, I think it would be more consistent with git-cliff's existing design to rely on next_version for the increment logic instead of introducing custom handling.

The decision not to use the existing --bump flag was intentional. My thinking was that a user might want to request both a major-level bump and a pre-release at the same time. In that case, combining everything into a single flag felt limiting, so I introduced a separate flag for pre-releases.

This is probably the most debatable part of the change.

After reconsidering it, I agree that introducing a separate flag for prereleases can make sense if we want to support combinations like a major bump together with a prerelease. However, I still think the new flag should conceptually depend on --bump, rather than behave as a fully independent option.

For example, something along the lines of:

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

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

As you mentioned, a user might want to request both a major level bump and a prerelease at the same time. Precisely because of that, the interaction between these flags becomes semantically significant and could easily shift user expectations around the existing --bump behavior.

Since this directly affects how version computation is interpreted, and potentially interferes with the current --bump semantics, I think it would be better to step back and discuss the intended specification and user-facing behavior in an issue first before finalizing the implementation.

@anagno

anagno commented Feb 24, 2026

Copy link
Copy Markdown
Author

@ognis1205 Should I create the issue or will you do it ?

@ognis1205

Copy link
Copy Markdown
Contributor

@ognis1205 Should I create the issue or will you do it ?

Could you create it?
I think it would be helpful since you have the full context.

@anagno

anagno commented Feb 25, 2026

Copy link
Copy Markdown
Author

@ognis1205 @orhun I added a couple of UTs documenting what is happening with the next_version and the new added flag. More or less trying to implement some of the cases mentioned in the issue

@anagno
anagno marked this pull request as draft March 25, 2026 15:31
@anagno
anagno force-pushed the feat/pre-releases branch 4 times, most recently from 14f2694 to 4871232 Compare March 25, 2026 16:18
@anagno
anagno marked this pull request as ready for review March 25, 2026 16:24
@anagno
anagno requested a review from ognis1205 March 27, 2026 09:26
@anagno
anagno force-pushed the feat/pre-releases branch 2 times, most recently from ecb7393 to c2c3d6a Compare April 4, 2026 20:31
@orhun orhun added this to the 2.14.0 milestone Apr 25, 2026
@orhun orhun modified the milestones: 2.14.0, 2.15.0 Aug 22, 2026

@orhun orhun left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • --release appears to be a no-op when used by itself. write_changelog calculates a version only when --bump or --bumped-version is set, and --release sets neither. Could you make --release trigger version calculation, or update the docs to show the required bump flag?

  • Also, finalizing a prerelease is now the default for any bump without --prerelease (1.2.0-rc.1 -> 1.2.0). That makes --release unnecessary when a bump is requested. Could you clarify which behavior is intended and align the flag and docs with it?

  • Lastly, --release sounds like a "release" action, maybe we can rename it to finalize-release or sth shorter? WDYT?

Add the possibility of  specifying pre-releases via the cli arguments.
Now it is possible to specify in the cli `--pre-release [type]` and the
bump version will be a prerelease

Signed-off-by: Vasileios Anagnostopoulos <anagnwstopoulos@hotmail.com>
@anagno
anagno force-pushed the feat/pre-releases branch from de9e963 to 1e34280 Compare November 2, 2026 10:40
@anagno

anagno commented Nov 2, 2026

Copy link
Copy Markdown
Author
* Also, finalizing a prerelease is now the default for any bump without `--prerelease` (`1.2.0-rc.1` -> `1.2.0`). That makes `--release` unnecessary when a bump is requested. Could you clarify which behavior is intended and align the flag and docs with it?

I tried to simplify it and I just removed the release flag. I added some more documentation, and the idea is that if it is not explicitly mentioned in the command line as prerelease, then it is incremented to a stable version

Is that better ?

@anagno

anagno commented Nov 20, 2026

Copy link
Copy Markdown
Author

@orhun Any comments on the latest changes ?

This branch has not been deployed

No deployments
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.

4 participants