Github milestones, fixes impacting multiple releases and moving away from backport strategy

[simonbasle]

This issue is for discussion around changing our process when an issue is needed in both the current development version (master branch) and one or more maintenance releases (I'm actually assuming we'll only consider the 3.1.x branch for now).

Too Long; Didn't Read version

We're considering switching to an issue triage, github milestone usage and branching model similar to that of Spring Boot (see branching wiki and triage wiki).

So Far

Until now, we've worked exclusively with backports, which we've always decided on doing after the original issue was fixed. It usually goes like this:

• a problem is discovered in the master branch, and an issue is created
• the issue is affected to what we expect to be the next feature release (out of master)
• the fix is developed against master
• we think about it and decide the fix is important enough to warrant a maintenance release of the previous GEN.MAJOR (eg. if master is 3.2.x then we decide we also want to release the fix in the 3.1.x cycle)
• we backport the fix from master to 3.1.x by cherry-pick
• we open or edit a "tracker issue" affected to the next 3.1.x milestone that will list the backports
• we edit the cherry pick commit message to change the title prefix to port, and reference the original commit AND the tracker issue in the commit message body

This is somewhat convoluted from a process perspective and although it makes it possible to see which fixes were backported from GitHub's UI, it is still hard. Also, from a git tooling perspective things are not so rosy (one can follow from the backport to the original fix by looking at the whole commit message, but the reverse is not possible).

Proposal: switch to a git merge scheme

This is inspired by what the Spring Boot team does.

⚠️Note that this scheme would force us to be more proactive on deciding wether a bug needs a fix in a maintenance release or not.

Here is how it would go:

• a bug is discovered in version 3.2.x
• we look at the bug and see if it is also present in 3.1.x. If it is, we decide wether or not it is impacting enough that it should be fixed in a maintenance release
• we affect the issue to the backlog milestone for the maintenance branch to mark it as triaged and targeting that maintenance branch
• the fix is worked on a branch created out of 3.1.x, multiple reviews on the PR can lead to multiple commits but we still prefer squash-and-merge where possible to result in a single commit on 3.1.x after the merge of the PR
• this is where additional manual steps are required:
• the 3.1.x branch is merged forward into master (git merge --no-ff 3.1.x)
• if there are any conflicts, meaning the fix impact a part of the code that has greatly diverged between 3.1 and 3.2, they are fixed immediately when the context of the fix is still fresh, and are made part of the merge commit.
• if the fix was targeting 3.0 instead, the merge step would be done twice: once from 3.0 to 3.1 and once from 3.1 to master.

Pros
The upside is that when it is in a maintenance branch, this process would guarantee that it is also in all subsequent maintenance branches AND master. It would also result in a single commit for the fix in all branches (plus GEN.MAJOR specific adjustments in the merge commit).

Cons
It adds noise in the commit history with merge commits, which should be made minimally descriptive:

• when adjustments were made, reflect it in the commit message "Adapt #issueNumber fix to 3.2"?
• when simple forward-merge, maybe use a simple title like "Merge #issueNumber fix into 3.2"?

GitHub milestones and release contents / release notes

Rationalizing our usage of GitHub milestones would also be beneficial with this scheme. Here is something that could work for us (again following the Spring Boot model):

• have backlog milestones receiving issues that we triaged and want in either the next feature release or a specific maintenance release, or at some point in the future.
• have .RELEASE milestones (or .M1, etc...) that match an exact release and reflect what is contained in this release and ready to ship with it.
• when fixing in maintenance branches, make sure that the release notes of subsequent releases in higher versions also list the issues.

For instance, with a master that contains active development on 3.2.0, with a second milestone in the near future and a planned maintenance release of 3.1.8.RELEASE, we would have milestones for triage:

• [icebox] (formerly [backlog]): issues that we want fixed at some point in the future but don't know when
• [backlog]: issues that we want fixed in the next feature release (3.2.0)
• 3.1.x: issues that we definitely want fixed within 3.1.x, but not necessarily in 3.1.8
• 3.2.x: issues that we definitely want fixed within 3.2.x, but not necessarily in 3.2.0

And milestones for shipping/tracking representative progress:

• 3.1.8.RELEASE: issues that are fixed from 3.1.x backlog are moved here. Open issues can also be affected here if we absolutely need that issue fixed in that particular version
• 3.2.0.M2: we're preparing a milestone 2 for 3.2.0 and issues that will ship with it are moved to this gh milestone, from [backlog], when merged. Open issues can also be affected here if we absolutely need that issue fixed in that particular version

[simonbasle]

Steps required to implement that change:

• Create [Backburner] and triage existing [Backlog] (probably most of it will go to [Backburner])
• Move all open issues from 3.2.0.RELEASE / 3.2.0.M1 to [Backlog]
• Do a second triage pass on [Backlog] and put issues that we'd want in the next maintenance release into 3.1.x.
• Prepare master branch for forward merges by doing an ours merge:

  git checkout master
  git merge -s ours 3.1.x
  

  • Reference this issue in the merge commit. The ours strategy will consider that any divergence in the 3.1.x branch is irrelevant and that the merge shouldn't change the state compared to the current HEAD.
• Prepare the 3.2.0.M2 diff for release notes right away, with the need to eliminate commits from 3.1.x from the diff using --first-parent... Later on one can use eg. git log --oneline --no-merges to avoid showing merges in history, or --first-parent to avoid showing the large number of divergent commits between 3.2.0.M1 and 3.1.x

[simonbasle]

What it looks like with various log command / tools (including a few fake commits and the merge commit that aligns master with 3.1.x):

• git log with no particular option (shows merges and 3.1 fixes, more or less git log --color --graph --abbrev-commit --oneline):

• IntelliJ default view when showing branches master and 3.1.x only:

• Using first-parent option (git log --oneline --graph --first-parent):

• IntelliJ with "IntelliSort" (displaying merged branch contents close to the merge commit):

• Using no-merges option (git log --oneline --graph --no-merges, we get "polluted" by the backport commits):

[simonbasle]

I've started with rationalizing the milestones in GH:
https://github.com/reactor/reactor-core/milestones?direction=desc&sort=title&state=open

Names to be refined, but at least the content follows the semantics above: triage milestones / backlogs only contain open issues, precise version milestones contains closed issues ready to ship or open issues that would most likely block the release

[simonbasle]

We'll probably switch to this model once 3.1.8.RELEASE and 3.2.0.M2 are released next week.

[snicoll]

Sweet :)

[simonbasle]

Done on master, phew 😅
I'll unshamefully copy-paste the wiki pages from Spring-Boot and adapt 😛