Project

General

Profile

Bug #16405

release_process: fix mind-boggling instructions for --previous options

Added by CyrilBrulebois 7 months ago. Updated 5 months ago.

Status:
Resolved
Priority:
Elevated
Category:
-
Target version:
Start date:
01/29/2019
Due date:
% Done:

100%

Feature Branch:
doc/16405-previous-iuks
Type of work:
Contributors documentation
Blueprint:
Starter:
Affected tool:

Description

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 iuk in ${IUK_SOURCE_VERSIONS?:}

Associated revisions

Revision 625ceaf0 (diff)
Added by anonym 6 months ago

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
said later:

Note that multi-steps incremental upgrade paths are valid and
supported [...]

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.

Revision 25f8ab65 (diff)
Added by intrigeri 5 months ago

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
in $ISOS/.

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

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.

Revision 5016a8d3 (diff)
Added by intrigeri 5 months ago

Release process: make example command work for alpha and beta releases too (refs: #16405).

Revision 79144c70 (diff)
Added by intrigeri 5 months ago

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.

Revision d46c4837 (diff)
Added by intrigeri 5 months ago

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.

Revision e390dd34 (diff)
Added by intrigeri 5 months ago

Release process: group path arguments on one side and version-related arguments on another (refs: #16405).

Revision 1d0b8003
Added by CyrilBrulebois 5 months ago

Merge branch 'doc/16405-previous-iuks' (Fix-committed: #16405).

History

#1 Updated by anonym 6 months ago

  • Status changed from Confirmed to In Progress

#2 Updated by anonym 6 months ago

  • Assignee changed from anonym to intrigeri
  • % Done changed from 0 to 50
  • QA Check set to Ready for QA
  • Feature Branch set to doc/16405-previous-iuks

@intrigeri, could you just double-check that I didn't mess this one up?

#3 Updated by intrigeri 6 months ago

intrigeri, could you just double-check that I didn't mess this one up?

Thanks! I'm on it. I'll come up with a proposal that fixes the obvious UX problem we have here, without removing useful info.

#4 Updated by intrigeri 6 months ago

  • Target version set to Tails_3.13
  • QA Check changed from Ready for QA to Dev Needed

#5 Updated by intrigeri 6 months ago

  • Priority changed from Normal to Elevated

#6 Updated by intrigeri 5 months 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 5 months ago

intrigeri, could you just double-check that I didn't mess this one up?

Meta:

  • 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 5 months 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.

#9 Updated by CyrilBrulebois 5 months ago

  • Status changed from In Progress to Fix committed
  • % Done changed from 50 to 100

#10 Updated by CyrilBrulebois 5 months ago

That looks very good, thanks!

Merged into master with fix-committed; will open a fresh ticket if there are still unclear things.

#11 Updated by CyrilBrulebois 5 months ago

  • QA Check changed from Ready for QA to Pass

#12 Updated by CyrilBrulebois 5 months ago

  • Status changed from Fix committed to Resolved

Also available in: Atom PDF