[FEATURE] Add flag to create release candidate release (x.y.z-rc.1)

[hannesortmeier]

Feature Request

Add a flag to verscout to create release candidate releases.

Motivation

To deploy to my dev instances, I need rc-releases. At the moment, I always concatenate a timestmap to the version that verscout outputs. But that way I always generate a new release since my comparision (last_version == next_version) is always false, even if there are no commits present, that would bump the version. If verscout would be able to check for the latest rc release, the comparison would again be true for releases with no bumpable commits.

I can of course work around it, but it would involve a few lines of bash and I would rather see verscout do the calculations and comparisions.

Proposed Solution

When a --rc flag is passed, verscout fetches the last full-release version and, if available, the last release-candidate version. rc-versions always follow the format x.y.z-rc.<incrementing number of candidates>.

The following describes the behaviour when the --rc flag is set:

next_version

• If a rc-release is available and no bump is needed, the last rc-release-version is passed as next version.
• if no rc-version is available and no bump is needed, return the full version as next version
• If a bump is needed, the last regular-version is fetched, bumped and a rc-version is returned as last version

last_version

• if a rc-release is available, return the rc-version
• if no rc-release is available and there is no version bump, return the last full-version
• if no rc-release is available and there is a version bump, return the last full-version

[erNail]

Thanks for opening a feature request! I was already thinking about adding release candidate/prerelease support.

I would call the flag --pre-release, since this is the term used by semver.org.

To adhere to different standards, and to increase flexibility for the user, i'd prefer to have some configuration options. semver.org states the following:

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.

While [PEP 440] allows only the following:

X.YaN   # Alpha release
X.YbN   # Beta release
X.YrcN  # Release Candidate
X.Y     # Final release

And these are only the standards i know about. It might be a good idea to let the user define the format themselves. But there always needs to be a digit at the end. So for example, the user could set a --pre-release-format to -rc. or rc or alpha or -alpha.. With the default being -rc.. verscout would then always expect the semantic version, followed by the defined format, followed by a digit.
This is not flexible enough to handle versions like 1.0.0-0.3.7, but there is simply no way to support all possible formats.

Another thing to think about: Should existing pre-release versions be ignored if no --pre-release flag is set? Should verscout do something similar like semantic-release, where the user can set certain branches on which pre-releases should or should not happen?

I still need to think through some of these questions, but i'd like to hear your input.

[erNail]

A first proposal on top of my head (not final, i'd still like your input):

We introduce new flags --pre-release and --pre-release-format (Idea for a better name?). The default format is -rc.

The pre-release version must end with a digit.

When set for the latest command:

• If a tag with the specified pre-release format exists, print it to STDOUT
• If no tag with the specified pre-release format exists, apply the currently existing non-pre-release logic (Check for a semver tag, write to STDOUT if it exists, otherwise write nothing to STDOUT and log that no tag was found)

When set for the next command:

• If a tag with the specified pre-release format exists and if conventional commits that should cause a bump exist, we increase the last digit by 1
• If no tag with the specified pre-release format exists and if conventional commits that should cause a bump exist, we apply the current existing logic (bump the version), and add the specified format and the digit 1.
• If no conventional commits that should cause a bump exist, we apply the current logic (Print nothing to STDOUT, log that no version bump will occur)

I think this gives the user the most flexibility, and it will not influence existing behavior. They have to decide when to use the --pre-release flag themselves. While this is not the most comfortable way for the user, it's the most configurable. We don't want to make assumptions about when a user wants to perform a pre-release. I'm used to performing pre-releases when not on the default branch main, but there are certainly other workflows.

[erNail]

Opened branch feature/pre-release-support to test some things and add the first changes. Feel free to use the branch to get a better idea of what i described. Also, feel free to use it as inspiration, or commit your own changes to the branch. I'm not sure how much time i'll find during the next week to work on this.

[hannesortmeier]

I like your idea.

This is not flexible enough to handle versions like 1.0.0-0.3.7, but there is simply no way to support all possible formats.

I think it would be flexible enough by setting --pre-release-format to "-0.3.7". If you want such a "complex" pre-release versioning, you might need to implement that part yourself. I think implementing this logic would go against verscout use case of being simple to use.

When set for the next command:

• If a tag with the specified pre-release format exists and if conventional commits that should cause a bump exist, we increase the last digit by 1
• If no tag with the specified pre-release format exists and if conventional commits that should cause a bump exist, we apply the current existing logic (bump the version), and add the specified format and the digit 1.
• If no conventional commits that should cause a bump exist, we apply the current logic (Print nothing to STDOUT, log that no version bump will occur)

That way, pre-releases with two semantic versions e.g. 1.0.0-0.3.7 are not possible but in my opinion that is totally fine. Since these are pre-releases, stability is not guaranteed anyway and a incrementing number should be enough for 99% of projects.

We introduce new flags --pre-release and --pre-release-format (Idea for a better name?). The default format is -rc.

I would'nt introduce two new flags but only one (e.g. --pre-release-format) and if set, it would implicitly imply, that a pre-release should be created.

[erNail]

That way, pre-releases with two semantic versions e.g. 1.0.0-0.3.7 are not possible but in my opinion that is totally fine. Since these are pre-releases, stability is not guaranteed anyway and a incrementing number should be enough for 99% of projects.

I also think it's fine. If the user wants to use pre-release versions that don't end with a digit that should be increased, he needs to implement his own logic for handling pre-releases in his scripts/CICD pipelines.

I would'nt introduce two new flags but only one (e.g. --pre-release-format) and if set, it would implicitly imply, that a pre-release should be created.

I was also thinking about this. But if we only use one flag, we can't set a default. The user would always have to pass the format.

It's essentially verscout next --pre-release vs verscout next --pre-release-format "-rc." if the default is -rc..
As a user, i think i'd prefer the option to simply use --pre-release, and only care about setting a format if the default one does not fit my needs.

But i can also see why only one flag might be preferable. But i guess then we should also change the flag name, so that it's clearer that this flag also enables the pre-release handling. What do you think?

[hannesortmeier]

I feel like having no default might be more declarative and easier to read. Seeing verscout --pre-release next vs verscout --pre-release "-rc." next, the second option makes it pretty clear, that the pre-release part starts with "-rc.". Also, as you have said, the more common name is pre-release instead of release-candidate, so even if you decide on an default, "-rc."might not be the best.

[erNail]

Sounds good, i'm convinced. Let's add a flag --pre-release that expects a string to be passed.