release_process: fix mind-boggling instructions for --previous options
Spotted during the 3.10, 3.11, and 3.12 release processes…
The instructions regarding the
--previous options to pass to
./bin/tails-iuk-generate-upgrade-description-files are rather confusing and almost entirely the opposite of current practice; the latter would rather be: pass
--previous $iuk for each
Release process: automate "mind-boggling" manual step (Will-fix: #16405).
Regarding this removed part:
Older versions for which there is no incremental upgrade path to
the new release must be passed with `--previous-version` [...]
We haven't been doing this at all for a long time because of what's
Note that multi-steps incremental upgrade paths are valid and
We've instead been pushing these multi-step upgrades hard, so we've
basically never followed these instructions, so let's just kill them
for the benefit for future, stressed out RMs.
Release process: remove duplicate info (refs: #16405).
Much of our release process relies on the assumption that generated files land
in some well-known directory, whose path is stored in an environment
variable to allow RMs to configure it, e.g. $ISOS.
So for example in this case, as long as one follows the instructions in the
previous section, this constraint is satisfied already: IUKs are generated
Release process: automate (refs: #16405).
Let's avoid the RM having to think about things that can easily be automated,
even if they're simple in isolation. Let them focus on the hard bits.
Release process: make example command work for alpha and beta releases too (refs: #16405).
Release process: automate all the UDF generation bits that can easily be (refs: #16405).
Again, let's avoid the RM having to think about things that can easily be
automated, even if they're simple in isolation. Let them focus on the hard bits.
Besides, this gets rid of all the "oh by the way you should have done X, Y and
Z" the RM might discover after having run the example command already:
the only changes they might have to apply to the example command are now
documented before the command itself.
Release process: explain both the general case and exceptional ones wrt. UDF generation (refs: #16405).
625ceaf03f6fc93e077acb1c95ce2cb6fa9871b9 automated the general
case, which is super cool; but it also:
- Removed all the (arguably very bad) instructions we had wrt. corner cases.
Without any explanation whatsoever, most RMs won't be able to guess whether
they're in one of these corner cases; I bet they'll always assume they're in
the general case and run the example command as-is (while previously they
would have asked someone more familiar with our incremental upgrade system
what they should do).
- Left in place an explanation that did not match the code anymore.
This commit adds explanations of what we're trying to achieve (from the user's
PoV), how that's expressed in the example command, what the corner cases are and
how to deal with them. Hopefully these explanations will be less mind-boggling
than the previous version we had; even if they probably have plenty of problems,
I hope they'll be a good enough basis that we can improve as needs arise.
Release process: group path arguments on one side and version-related arguments on another (refs: #16405).
#6 Updated by intrigeri about 1 month ago
- Assignee changed from intrigeri to anonym
- QA Check changed from Dev Needed to Ready for QA
@anonym I've tried something, please let me know what you think. Feel free to summarily merge into master (if this doc looks better, at first glance, than what we have in there) and use the 3.13 release process as a "user" testing session for these instructions.
Once merged into master, please postpone this ticket to 3.14 and reassign to kibi for another round of review, that he can do while RM'ing 3.14 (he's the one who formally raised this issue initially and I bet he'll find at least a few mind-boggling bits in the newly written doc :)
Thanks in advance!
#7 Updated by intrigeri about 1 month ago
intrigeri, could you just double-check that I didn't mess this one up?
- I acknowledge that the current instructions are mind-boggling, unclear, confusing, etc. And I think that anonym's reasoning, that's behind the commit message, is correct (even though the exact phrasing reveals the depth of the misunderstanding and thus how bad the current doc is). I.e. on what matters most, we're on the same page! :)
- this piece of doc has grown over time when other RMs (mostly anonym) asked me to add info and expand it; I obviously did not do a good job at it but summarily removing information, that was meant to answer actual questions RMs have asked themselves/me, feels like a regression. If we only did that I'm concerned that we'll re-add that info later, in one form or another, every time a RM gets confused or does a mistake due to lack of information. I'd rather spend time to fix the doc now, without losing useful info along the way. I thought the most efficient way for me to do so was to propose a branch and explains my rationales in the commit messages, instead of trying to convey my ideas to you here. So that's what I've done.
#8 Updated by intrigeri about 1 month ago
- Assignee changed from anonym to CyrilBrulebois
@CyrilBrulebois can you please review this? If you prefer, feel free to summarily merge into master (if this doc looks better, at first glance, than what we have in there) and use the 3.14 release process as a "user" testing session for these instructions.