Intuitive phase terminology

[sbp]

Our current phases are:

1. RELEASE_CANDIDATE_DRAFT
2. RELEASE_CANDIDATE_BEFORE_VOTE
3. RELEASE_CANDIDATE_DURING_VOTE
4. RELEASE_PREVIEW
5. RELEASE_BEFORE_ANNOUNCEMENT
6. RELEASE_AFTER_ANNOUNCEMENT

Colloquially, we call these draft (1), candidate (2 and 3), preview (4), and release (5 and 6).

This is confusing for several reasons. There are two phases for candidates, and two for releases. All phases are releases but we only refer to phases 5 and 6 as releases because we shorten e.g. "release candidate draft" to just "draft". Phase 2 could just as well be considered a draft as a candidate. The release process ends upon moving to phase 6, so it's not clear that phase 6 is needed. And none of these phases characterises what the release manager should be doing at each phase.

What if we used verbs instead?

1. Edit
2. Review
3. Vote
4. Tweak
5. Announce

These are what release managers need to be doing in each phase. Edit the release, then freeze it. Review it, then send the vote announcement. Vote, then resolve the vote. Tweak versions, then freeze it again. Announce, then make it available to the public.

It makes sense to talk about the "edit phase", the "review phase", the "vote phase", the "tweak phase", and the "announce phase". It allows us to think of phases as what you do to a nascent release, instead of trying to have different nouns for each phase and then pairs of phases like we are doing currently.

[sbp]

Alternatives:

1. Compose
2. Review
3. Vote
4. Prepare
5. Announce

[dave2wave]

Thanks for starting this discussion. I need to think this through more clearly, but I have observations.

1. In the overall design we have Distribution steps that were intended approximately for RELEASE_CANDIDATE_BEFORE_VOTE and RELEASE_PREVIEW.
2. I'd like to simplify the number of steps. Perhaps, we should prepare to have some transitions include actions.

A shortened list of phases aligned with Activities could be:

1. Compose. Which includes Draft, Future Test Distributions, and instead of Promote call it Start Vote.
2. Vote or Approve.
3. Distribute. Which includes activities like Distributions, Extra signing, and composing the Announcement. the final part of the phase would be to move the approved Candidate into Release and send the email.

There would be no skipping of steps.

[sbp]

The current idea of RELEASE_CANDIDATE_DRAFT ("Compose") and RELEASE_CANDIDATE_BEFORE_VOTE ("Review") is that drafts ought to be frozen before the vote announcement is made. We could freeze the draft when the vote announcement email is sent, instead, but that opens the possibility of a race condition. If the draft is still editable, the RM could look at the draft, think "it's ready for the vote", and then another participant could edit the draft just before the vote email is sent.

It's the same case with RELEASE_PREVIEW ("Prepare") and RELEASE_BEFORE_ANNOUNCEMENT ("Announce"). The Announce phase is just Prepare once it's been frozen. In this case a race condition is less likely, however, because the number of contributors allowed to edit the release at Prepare stage should be minimal, carefully controlled, and audited. Similarly, the range of edits that are allowed to be performed should be strictly limited. Despite this, there would probably be multiple people with the permissions to make edits during the Prepare phase, and so a conflict is once again possible.

We could think of these pairs of phases (Compose and Review, and Prepare and Announce) as being a single phase with a mutability bit set instead. Compose (mutable) and Compose (immutable); Prepare (mutable) and Prepare (immutable). We'd have to have a good think about how to make the UI for this clear to users. What we really want to discourage is making a release immutable and then immediately promoting it to the next phase. The point of making a release immutable before it's moved to the next phase is that now it can be checked without having to worry that the release is going to change after a review. For simple releases with just a few files and a few contributors, this is unlikely to matter very much. For releases with dozens of files, lots of last minute changes, and other complexity, it's more likely to be important.

[sbp]

We can use the revision mechanism to remove the RELEASE_CANDIDATE_BEFORE_VOTE and RELEASE_BEFORE_ANNOUNCEMENT phases. As long as the UI is clear about which specific revision is being promoted, and as long as the backend code validates that there were no new revisions meanwhile, there can be no undetected conflicts. If there is a conflict, we can just notify the user.

[dave2wave]

Currently we have:

1. Compose
2. Vote
3. Refine - I think that Deploy would be better.

[sbp]

Changed from refine to deploy in 3166e6b8.

What I was hoping to do is have a phase verb and then a separate verb for the promotion. So for example we would have:

1. Compose (and "Start vote" to promote)
2. Vote (and "Resolve vote" to promote)
3. Refine (and "Announce" to promote)
4. Distribute

At one point I was using "Announce and distribute" for the phase 3 promotion verb, but shortened it again to just announce.

I think that "Deploy" would be more suitable as an alternative to "Announce", i.e. to be used as a promotion verb, than as a phase verb. What do you think? In other words:

Refine (and "Deploy" to promote)

I wasn't keen on refine either, but the only alternative that I could think of was adjust. I was trying to encapsulate the idea that this is the phase where adjustments or refinements are made before the actual deployment. The deployment would be final, no adjustments or refinements after that!

[dave2wave]

What do you think of "Complete" or "Finish" (and "Deploy" to promote)?

[sbp]

"Complete" has the disadvantage of also being an adjective: "ah, that's complete! That means I don't have to do anything more to it." I considered Finalise and Polish, but rejected the latter because it was too colloquial. That leaves us with Adjust, Refine, Finalise, and Finish to choose from.

[dave2wave]

Given those four choices "Finish" is best.

[sbp]

Renamed to Finish in ae6409b6 and df8a5bd6.