doc: RFC for handling prerelease strings. ref #510

[broofa]

Per this comment in #510, creating an RFC doc for specifying how prerelease versions should be handled.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[chingor13]

Thanks for submitting this. We are definitely open to adding additional versioning strategies.

Additional considerations:

• which commit types influence each version bump
• how (or if) the primary semver numbers will change
• how (or if) the release becomes non-prerelease

Additional note: we added a prerelease versioning strategy that follows our googleapis/google-cloud-dotnet libraries handle pre-release versioning in #1981. If that one does not suit your needs, it could be used as a blueprint for a similar new versioning strategy.

[broofa]

@chingor13 Thanks for the feedback. You ask good questions. If you don't mind, I'd like to reply here and get your thoughts before updating the PR...

Additional considerations:

• which commit types influence each version bump

This is a tricky question.

For starters, the Conventional Commits spec doesn't address prerelease fields at all. There's simply no mention of "prerelease" in the spec. I suspect this is because the authors don't consider the prerelease field to be versionable in the way "primary fields" (major / minor / patch) are.

Yet the SemVer spec does devote a fair bit of verbiage to the prerelease field. Notably, it says "Pre-release versions have a lower precedence than the associated primary version". But, unlike the minor and patch fields, no guidance is given on how it should behave when higher-precedence fields are bumped. E.g. The patch field "MUST" be set to zero if either the major or minor fields is incremented. But it says nothing about the prerelease field.

Furthermore, in practice the prerelease string is most-often used to track "significant" branches of development off the main branch. For example it's not uncommon for a project that has a 1.x release in production to push out a 2.x beta release with semvers like "2.0.0-beta-1". The semantic being, "this is a candidate for the 2.0.0 release".

But what happens if someone adds a "BREAKING CHANGE" commit to that branch? Does the version get bumped to "3.0.0-beta-1"? That's what Conventional Commits would ordinarily mandate. And if I'm reading the prelease versioning strategy PR you link to properly, that's what would happen there, right?

... but that doesn't really make sense. In this [common] scenario, the breaking change is redundant with the fact this is a "2.x-beta" candidate.

In other words, if a semver has a prerelease field then I think the assumption needs to be that the primary fields reflect the intended version, once the prerelease tag is removed. As such, if a prerelease field is present I don't think the commit type should influence primary fields.

• how (or if) the primary semver numbers will change

See above. tl;dr: They shouldn't.

• how (or if) the release becomes non-prerelease

See above. I think the conclusion is that the prerelease field is removed, with no change to the primary semver numbers.

Additional note: we added a prerelease versioning strategy that follows our googleapis/google-cloud-dotnet libraries handle pre-release versioning in #1981. If that one does not suit your needs, it could be used as a blueprint for a similar new versioning strategy.

Interesting. I wasn't aware of this work. My initial reaction is that this seems complicated and problematic. Again, if a semver has a prerelease field, I think the semantic needs to be that the primary fields are the intended version upon actual release and, as such, shouldn't change.

Thoughts?

[broofa]

So... I may need to backpeddle on all of this. I was only considering major-prerelease versions. I wasn't thinking about lessor versions like "2.3_beta.1". 😬

When you start thinking through the lessor-version scenarios, I think you kind of inevitably land on a prerelease strategy like the one you've implemented for googleapis/google-cloud-dotnet.

I need to think through this further but, alas, don't have time at the moment. Before I go, though, I'll note that the semver module has a bunch of test cases for bumping prereleases. Do you happen to know if the prerelease strategy you've implemented aligns with those?

[thebergamo]

If you don't mind I would like to add my two cents here, even thought I think it should be covered in the test cases aforementioned.

In general, coming from for example semantic-release module, I would expect that the pre-release would be just a case to be bumped based on the build itself (of course considering changes).

For instance, if in my first commit to introduce this new release would be simply some new feature, we should just bump the minor version, but if for some reason we have to introduce a BREAKING CHANGE it should simply bump major and reset the pre-release version(as per proposed being .0 again).

If after first Breaking change other breaking changes or features get added, it shouldn't change the target version for example 1.0.0.rc-0++(++ in here is just to refer as incrementing this version) same as other bumps if they happen, the most important is bumped and pre-release restart the increments only if version changes.

This is very useful feature for example in cases were we have this PR releases as things are there to be released in a trunk(for sprint wise for instance) but we would like still to be able to pre-release to some environment for some QA tests for instance and having the pre-release there would be nice for visibility of the versions being tested and linked to the PR as well.