Project

General

Profile

Bug #16600

release_process: please clarify versions

Added by CyrilBrulebois 2 months ago. Updated 2 days ago.

Status:
In Progress
Priority:
Normal
Category:
-
Target version:
Start date:
03/21/2019
Due date:
% Done:

0%

QA Check:
Ready for QA
Feature Branch:
master
Type of work:
Contributors documentation
Blueprint:
Starter:
Affected tool:

Description

If there should be a single issue I faced during the 3.13 release process, this is the one.

There are a fair number of assumptions in release_process.mdwn, including the rhythm of major and bugfix releases. At least: one is expected to know about the next major release, and about the one after that! Which isn't the case right now, as we have a number of bugfix releases in a row, followed by a major release which has an unknown version number (3.17 or 4.0). Admittedly, this could be called a corner case, but it's bound to be repeated for at least 3.14, and maybe 3.15, depending how far ahead scheduling (major) releases is going to happen.

I've tried to adapt as best as I could the instructions so they would make sense, targetting the next two releases (3.14 and 3.15, both bugfix); I've also opened #16572 and asked another RM to look at it urgently (again, thanks for the swift answer) to make sure what I was doing wasn't entirely crazy. I didn't read all the reply (#16572#note-1) and stopped at “tl;dr: for 3.13, go for what you did already; for next time, read what follows.” and a similar “it's fine, carry on” on XMPP.

But the next day, I tried to follow the post-release steps (which for various organisational reasons I managed to dodge most times until now…) to put 3.17 as the next major version in the devel branch, which I'm told would break the test suite.

I find it very hard to:

  1. decide what should be set through various environment variables. This has gotten better with the great MAJOR vs. BUGFIX renaming/clarification rounds though. But that started with some kind of cargo-culting, copying and pasting the RM's file for the previous release, and trying to guess what should be bumped.
  2. understand all the implications of specifying this or that version at a given step. While this might be OK if one were able to follow the release process documentation blindly, experience for all RMing iterations I've taken part in shows that there are always exceptions and deviations that one should be prepared to operate.

Therefore, I would very much welcome some kind of “definitive guide to versions” that would help RMs remember everything there is to know about versions/branches/etc.; or at the very least, help RMs operate consistent choices when they have to deviate from the release process documentation.

Again, looking at previous release cycles, there are always many things to prepare on release day 1, the release itself to publish on day 2 (usually waiting on the MFSAs, so we cannot expect to finish everything on that day, even for a night owl like me), and post-release steps. Given how busy days 1 and 2 are, even with more experience, I don't think I'll ever manage to get post-release steps done before day 3. And keeping a train of thoughts over 3 days doesn't seem realistic, at least to me (e.g. if I had read and understood the last part of #16572#note-1 on day 1, I wouldn't have thought about it and anticipated all the consequences, when performing post-release steps on day 3).

Associated revisions

Revision d30a11a9 (diff)
Added by intrigeri 2 months ago

Calendar: give a canonical version number to the 2019-10-22 release (refs: #16600)

This should help RMs decide how they should set $NEXT_PLANNED_MAJOR_VERSION.

Revision dd14b778 (diff)
Added by intrigeri 2 months ago

Release process: avoid having to guess when it's not needed (refs: #16600)

kibi wrote "one is expected to know about the next major release, and about the
one after that". I assume that's about $SECOND_NEXT_PLANNED_MAJOR_VERSION.
In the general case, indeed we don't always know what that version will be.

Thankfully, we only need this variable when preparing a RC for a major release,
in which case all the RM needs to know is 1. the version number of that major
release (the RM has to know that anyway); and 2. the version number of the major
release after the one the they're preparing (in general we have a release
schedule for the next 6-12 months, which includes this info).

So let's only set this variable when we need it, i.e. when it's rather easy
to find out what its value should be: as kibi said, right now we have
no idea what will be the major release after 3.17.

Revision 9b428474 (diff)
Added by intrigeri 2 months ago

Release process: clarify what does not need to be adapted (refs: #16600)

Given we're going to have a bunch of bugfix releases in a row, recent RMs have
been tempted to set $NEXT_PLANNED_MAJOR_VERSION to one of them, assuming that if
they didn't do so, the rest of our release process doc would be buggy because
said doc assumes strictly alternating bugfix/major releases. AFAIK this is not
the case: to the best of my knowledge, the release process doc makes no such
assumption anymore (it used to, but we've been in such a situation already
and had to make the doc support it).

So clarify that this part of the release process doc can be followed blindly.

Revision 8c8d5467 (diff)
Added by intrigeri 2 months ago

Release process: add some structure (refs: #16600)

Revision c832a971 (diff)
Added by intrigeri 2 months ago

Release process: clarify variable vs. constant (refs: #16600)

Some of the trouble kibi suffered from was caused by changing the value of
$NEXT_PLANNED_MAJOR_VERSION in the middle of the release process. Let's clarify
that these variables should be thought of as constants throughout the
release process.

Revision 5db3b595 (diff)
Added by intrigeri 2 months ago

Release process: document what the $NEXT*VERSION variables are used for (refs: #16600)

This should help understand the implications of changing their value
in the middle of the release process.

History

#1 Updated by intrigeri 2 months ago

  • Assignee set to intrigeri
  • Target version set to Tails_3.14

#2 Updated by intrigeri 2 months ago

  • Status changed from Confirmed to In Progress

#3 Updated by intrigeri 2 months ago

  • Assignee changed from intrigeri to CyrilBrulebois
  • QA Check set to Ready for QA
  • Feature Branch set to master

There are a fair number of assumptions in release_process.mdwn,

Oh yes.

including the rhythm of major and bugfix releases.

I didn't notice any such assumption while following that doc for 3.13.1. But it's entirely possible that my trained brain adjusted things without me noticing consciously :) Is there a specific part of that doc that suggests so?

At least: one is expected to know about the next major release,

Right → d30a11a9253e61de8270e3996c4dcf4ab2e1f507

and about the one after that!

Actually, not in cases in which this would be any harder than knowing about the next major release… but you're right, the doc didn't make this clear, and that surely didn't help you follow blindly other instructions that should have been followed as-in → dd14b7789b63152d00352e1e891a01c25b14d0d1 should help.

But the next day […] to put 3.17 as the next major version in the devel branch, which I'm told would break the test suite.

I hope 5db3b5953ff853e9e1739bfcb6661b02fc197595 will help.

I find it very hard to:

decide what should be set through various environment variables. This has gotten better with the great MAJOR vs. BUGFIX renaming/clarification rounds though. But that started with some kind of cargo-culting, copying and pasting the RM's file for the previous release, and trying to guess what should be bumped.

Understood. I would suggest that next time, you start this environment file from scratch wrt. the version numbers, and then follow the doc. This should help spot whatever remains unclear there :)

understand all the implications of specifying this or that version at a given step. While this might be OK if one were able to follow the release process documentation blindly, experience for all RMing iterations I've taken part in shows that there are always exceptions and deviations that one should be prepared to operate.

ACK. 9b4284745a250975a992a99df55607933e5e6c28, 5db3b5953ff853e9e1739bfcb6661b02fc197595 and c832a9710c15efe392a8f5750957746eaf90d90c should help.

Therefore, I would very much welcome some kind of “definitive guide to versions” that would help RMs remember everything there is to know about versions/branches/etc.; or at the very least, help RMs operate consistent choices when they have to deviate from the release process documentation.

Wrt. versions, I'm afraid I wouldn't really know what else to write in such a "definitive guide" than what I've added in the commits you'll see in the "Associated revisions" section on the ticket. I'm happy to keep clarifying and adding whatever info is missing.

Wrt. branches, if something is missing on https://tails.boum.org/contribute/git/#branches, please let me know.

Given how busy days 1 and 2 are, even with more experience, I don't think I'll ever manage to get post-release steps done before day 3

I'm pretty sure you will, once our doc deserves your trust more and you build more confidence in your own ability to assess whether you need to deviate from the doc :)

#4 Updated by CyrilBrulebois 2 days ago

  • Target version changed from Tails_3.14 to Tails_3.15

Also available in: Atom PDF