[jakartaee-spec-project-leads] Milestone releases was: Milestone release

[Mark Thomas <markt@xxxxxxxxxx>]

On 09/01/2020 02:58, Bill Shannon wrote:

Thanks Bill, this is really helpful.

Moving servlet-dev to BCC and adding spec-project-leads

> This is not the way we intend milestone release numbering to work.
> This introduces another level in the release numbering.  What we want
> is qualifiers on the existing release numbers.

Agreed.

> So, just like "5.0.0-SNAPSHOT" is a qualifier on the 5.0.0 release
> saying that this is just a "day in the life" version of the 5.0.0
> work, "5.0.0-M1" would be the first milestone build on the way to
> the 5.0.0 release.  "5.0.0-RC1" would be the first release candidate
> on the way to 5.0.0.

Also agreed. I have used .M1 rather than -M1 elsewhere but I agree -M1
is better. I'll switch to that format moving forwards.

> A release number such as "5.0.0.M1-SNAPSHOT" looks like a "day in
> the life" release of what will be the final 5.0.0.M1 release, which
> would be a stable release coming after the final 5.0.0 release.  This
> takes us down the slippery slope that I warned about previously with
> using milestone releases as a way around the process overhead of doing
> a full Jakarta EE release.  We don't want milestone releases to look
> like final releases.

Agreed.

> Maybe this is the key difference between using "-" and "." as a
> separator - dash introduces a release qualifier, whereas dot adds
> another level to the release numbering hierarchy.

Makes sense.

> I understand that some of this is open to interpretation, and different
> communities might have different conventions for how this should be done,
> but for Jakarta EE and EE4J I would strongly recommend that we stick with
> three level release numbers with qualifiers to indicate non-final releases.

Agreed.

> So, to update your plan, you would change the version number to 5.0.0-SNAPSHOT.
> When the milestone release is ready, you would change the version to 5.0.0-m1
> in the release job, do the release, and then the release job would change it
> back to 5.0.0-SNAPSHOT.  If a second milestone is needed, you would change the
> version to 5.0.0-m2 in the release job, do the release, then change back to
> 5.0.0-SNAPSHOT.

ACK.

> Since non of these are final releases, the release script can't really pick the
> version number of the next release.  It can only recognize that you're doing a
> non-final non-SNAPSHOT release and switch the version number back to the
> appropriate SNAPSHOT version number after doing the release.

I think I was trying to get the release script to do too much and handle
the auto-increment from -M1 to -M2. Just setting the qualifier manually
is much simpler. I'll use that approach and tweak the release job
accordingly.

This means I shouldn't need to commit anything to the repo to get this done.

> You'll definitely want to create a tag for the 5.0.0-m1 release.  A branch might
> be needed as part of the release process, but it would be merged back into
> master and destroyed once the release is committed.

Agreed.

> BTW, I don't have a strong opinion as to whether we should use upper case or
> lower case for these qualifiers.  By analogy with -SNAPSHOT, upper case might
> be appropriate, although I've seen lots of use of lower case and that's what
> I've been using myself.  But it would probably be nice if we all agreed.
> 
> (This discussion probably needs to be moved to the project leads list or wider.)

Again, I've seen both.

On the basis it is consistent with -SNAPSHOT and it is what the Eclipse
IDE uses, I think we should use upper case.

Overall, I think we are in near complete agreement.

I do think it is worth clarifying exactly what we want the release job
to do (thinking just in terms of outputs, not how we get there). At the
moment, given a current version number of 1.0.0-SNAPHOT in master the
release job:
- creates a 1.0.0 release in the staging repo
- creates a 1.0.0 tag
- creates a 1.0.0 branch
- increments the version to 1.0.1-SNAPSHOT in the 1.0.0 branch

I don't understand the last item. I'd expect it to increment the version
number in the branch the release was made from. Have I missed something
or should I look into trying to change this?

Also, I think keeping the branch is unnecessary. Can we remove the
branch as part of the release job (or not create it in the first place)?

Further, I'd like to propose the following additional behaviour if a
QUALIFIER is configured for the release job. My proposal is given a
current version number of 1.0.0-SNAPHOT in master and a QUALIFIER set to
M1 the release job:
- creates a 1.0.0-M1 release in the staging repo
- creates a 1.0.0-M1 tag
- leaves the version number in master unchanged

Mark