Clarify and constrain permitted ASF TLP version numbers

[sbp]

From a comment I made on #386:

Many of our TLPs have current M[0-9]+ and rc[0-9]+ releases. Perhaps we should document and model this situation as encompassing internal (ATR revision or tag) pre-releases and external (M[0-9]+, rc[0-9]+ etc. in the finished release) pre-releases? But our release policy clearly says:

Projects MUST direct outsiders towards official releases rather than raw source repositories, nightly builds, snapshots, release candidates, or any other similar packages. [...] Do not include any links on the project website that might encourage non-developers to download and use nightly builds, snapshots, release candidates, or any other similar package.

In bold per the original. This may imply that TLPs have some kind of need that is not covered by the release policy, or that they are unaware of this part of the policy, or that I am misreading the situation. The policy also says:

Release Candidates are packages that have been proposed for approval as a release but have not yet been approved by the project.

Only approved packages can have a final release on ATR, so we should probably look for rc, alpha, beta, and milestone tags in submitted revision numbers and disallow or strongly warn the release manager. We allow such tags in filenames because they can be stripped out in the final phase before announcement, as a special case. This is a bit complicated but we thought it was a good compromise.

We should clarify which of the de facto or de jure situations needs to be reflected in ATR. Unless we hear to the contrary we will go with the de jure situation and follow the ASF release policy in forbidding version numbers which appear to contain a pre-release component.

[sbp]

Note that Airflow have an interesting approach to this: as I understand it, they build RC and non-RC tagged versions simultaneously, distribute the RC tagged versions to their participants for voting, but consider the vote to be held on the non-RC tagged versions which are then released. If there were a diffoscope style proof of minimal (tag only) differences between the artifacts, we could include this in the attestations that ATR makes. This should be reflected in the official ASF release policy, because at present this practice, if I understood it, is outside of that policy.

[raboof]

This may imply that TLPs have some kind of need that is not covered by the release policy, or that they are unaware of this part of the policy

The distinction the release policy is making is between "real Releases" and "not real Releases": "real Releases" are things that have been properly voted on by the PMC, "not real Releases" are all other things - the "raw source repositories, nightly builds, snapshots, release candidates, or any other similar packages".

As an example, Pekko is currently voting on 2.0.0-M1-RC1, and if this vote passes, this code will be released as 2.0.0-M1. The fact that this version ends in -M1 does not imply that it is a "not real Release", it is the other way around: the fact that we have properly voted on it as PMC makes it a "real Release". This is in line with the release policy - it does not forbid "version numbers which appear to contain a pre-release component" - for example the last bullet in https://www.apache.org/legal/release-policy.html#release-types explicitly highlights "real Releases" that are nonetheless "milestones intended only for bleeding-edge developers working outside the project".

[sbp]

Ah, thanks for clarifying. So it's a terminology distinction: on the one hand release candidates, which are not approved by a PMC and not distributed to the public; and on the other hand alpha, beta, and milestone releases, which are approved by a PMC and distributed to the public. But that doesn't explain why there are (?i)rc[0-9]+ releases such as Apache Lucene.NET 3.0.3-RC2:

https://dist.apache.org/repos/dist/release/lucenenet/3.0.3-RC2/

Perhaps these are considered alpha releases? In other words, what is the coupling of version number components to the release status grades in our release policy? Is it possible to release with "RC2" in the name despite the terminology "release candidate" being reserved in the release policy for unapproved, non-public releases?

[raboof]

If anything, it is incredibly confusing 😆. I'm not too familiar with the Lucene.Net project, but what I'd suspect has happened is that they first voted on an RC1, that vote failed, then they voted on RC2, that vote succeeded, and they just plopped the RC2 artifacts into the 'dist' folder without renaming them. That is not "wrong" - by passing the vote this RC is no longer just an RC but a "real Release" - but not having the name reflect that is of course confusing.

[raboof]

If so this would be an excellent example where hopefully the guidance of ATR would help them vote on the RC artifacts, and then after voting move them to the dist area while dropping the RC annotation ;)

[raboof]

So it's a terminology distinction: on the one hand release candidates, which are not approved by a PMC and not distributed to the public; and on the other hand alpha, beta, and milestone releases, which are approved by a PMC and distributed to the public.

It's possible that different PMCs use different terminology: it's possible that one PMC makes 'alpha' packages that are only meant for use internally to contributors/developers and are not voted on (i.e. "not real Releases"), while another PMC makes 'alpha' packages that are voted on and suitable for (bleeding-edge) developers outside of the project (i.e. "real Releases"). The main distinction is that if it's gone through the full release process (including vote) it's a "real Release", and if it's not, it's not.

what is the coupling of version number components to the release status grades in our release policy? Is it possible to release with "RC2" in the name despite the terminology "release candidate" being reserved in the release policy for unapproved, non-public releases?

I think the point is kind of moot: while I could go either way on whether I think the release policy forbids referring to the RC as "RC" after the vote has passed, in any case it's confusing and we shouldn't do that.

[sbp]

I think the point is kind of moot: while I could go either way on whether I think the release policy forbids referring to the RC as "RC" after the vote has passed, in any case it's confusing and we shouldn't do that.

Agreed. I think what I might do is add a JavaScript check to the page to start a release, on the form where you have to enter the version, and if it detects an rc-style tag in there it warns and documents why that's potentially a bad idea. Then the release manager is made explicitly aware of what they're deciding to do, and how ATR works.

Alternatives considered: adding a check, and forbidding rc-style tags entirely. We can't add a check for this because checks only apply to files within a release. Those might have rc-style tags too, of course, but we actually allow those tags in filenames because they can be removed before release. Also, the version cannot be changed after a release has started without deleting the whole release and starting again. We could forbid rc-style tags entirely, as I suggested above, but if the release manager is making an explicit choice even after we've documented exactly why rc-style tags should not be used for a finished release then there's probably an important reason for that and we'd at least know who the release managers are that we need to discuss this with.

[dave2wave]

If we going to disallow RC naming in the version name then we have to convince legal to modify Release Policy. I think we are ready to make a list of changes to policy we wish to propose.