Explain how to revert maintenance branch commits

[ncoghlan]

It came up in https://bugs.python.org/issue32690 that it's not at all clear how to revert commits to a maintenance branch if we decide that a change shouldn't have been backported after all.

Transferring over my notes from that issue to be cleaned up and added to the dev guide:

• check out the branch of interest and ensure it's up to date
• git checkout -b bpo-32690-revert-3.6-backport
• git revert 9105879bfd7133ecbac67f3e9c0bacf6e477de5a
• edit commit message as appropriate
• create a PR targeting the branch of interest: [3.6] Revert "bpo-32690: Preserve order of locals() (GH-5379)" cpython#5439

[rhettinger]

For the record, I initialized tried using Github's revert button on the original PR, python/cpython#5390 . However, it unhelpfully said this cannot be reverted automatically.

Next I tried command-line git:

41059  git fetch --all
41060  git checkout 3.6
41061  git log -1 Objects/frameobject.c
41062  git checkout -b undo_preserve_locals_order
41063  git revert 9105879bfd7133ecbac67f3e9c0bacf6e477de5a
41064  git status
41065  git diff 3.6
41066  git status
41067  git push origin 3.6:undo_preserve_locals_order

Next, I went back to my Github account to create the PR but the preview was showing it as many thousands of lines. This indicated that it was being applied against 3.7 instead of 3.6. There was no obvious way to change the target back to 3.6.

[Mariatta]

From what @rhettinger described, it seems that when reverting using GitHub web UI, GitHub by default selected the master branch, even though it was reverting from the 3.6 branch. I think GitHub should have known better to select the 3.6 branch in this case. 🤔

@ncoghlan, would you like to prepare the PR explaining how to revert? 😄

I'm now thinking that we might need a revert-bot one of these days 😁

[ncoghlan]

All of @rhettinger's steps were right, it's just that in the final PR creation step in the web UI it's necessary to know that there are some dropdowns in the top-left which allow you to choose which branch is the intended destination.

Once you adjust that from master to 3.6, GitHub correctly recalculates the diff and gives you a sensible PR. But if you don't already know the dropdowns are there, then there isn't anything to really draw your attention to them.

[ncoghlan]

Deciding how to add this is actually a bit tricky, since we don't currently discuss git revert at all, not even in the simpler case of reverting a commit to master.

Given that it was the PR interface that caused problems, perhaps it would be more useful to add a section on "Submitting a PR to a maintenance branch"? In https://github.com/python/devguide/blob/master/gitbootcamp.rst#backporting-merged-changes we currently gloss over that bit, since it relies on having cherry_picker.py generate a suitable PR URL.