[core-workflow] instructions for cherrypicking a change from master

[Chris Angelico]

On Sun, Oct 9, 2016 at 11:20 PM, Barry Warsaw <barry at python.org> wrote:
> On Oct 09, 2016, at 12:43 PM, Nick Coghlan wrote:
>
>>It probably makes more sense to assume a successful backport as the
>>default case
>
> We'll have to see.  Maybe Python's code won't change so much between major
> versions, but I've been on projects where refactorings and other changes do
> result in most cherry picks needing massage.

In my experience, CPython is stable enough that you can sometimes even
pick up a patch from *2.7* and apply it to the latest 3.x. (The
downside of this is that some files are oddly named, eg longobject.c,
which implements what we now call "int".) Between 3.5 and 3.6 it'll be
even more common for a patch to apply cleanly, and shortly after a
branch is cut (eg current 3.6 -> 3.7), near-certain.

And of the possible failure modes, "patch doesn't apply" is far more
likely than "patch applies but tests fail". In the former case, git
will tell you straight away; it's only in the latter case that you'll
need to amend the commit.

>>, and cover "git commit --amend" to handle the case where the tests fail -
>>the ease with which history can be rewritten prior to publication is the main
>>UX benefit git offers over hg, so we may as well take advantage of it.
>
> Yeah; I have a visceral reaction to history modification, but git does seem to
> be more amenable to that.  I can't check now, but what's the failure mode if
> you --amend a pushed commit?  IIRC, the --amend succeeds but you'll get an
> error on push, which IMO is later than it should be (i.e. git probably should
> disallow --amend on published commits).

It's pretty simple:

rosuav at sikorsky:~/Gypsum$ git push
To github.com:Rosuav/Gypsum
 ! [rejected]        master -> master (non-fast-forward)
error: failed to push some refs to 'git at github.com:Rosuav/Gypsum'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

(And attempting a 'git pull' will highlight the fact that you've
edited history.)

The server will want to be configured to utterly reject
"non-fast-forward pushes"; git actually does allow you to override the
above message ("git push --force-with-lease" and friends), but
ultimately, it's the central server that chooses to accept or reject
the push. It's possible, for instance, to accept a force-push on a
topic branch but reject them on your primary branches, which would
allow people to rebase their "proposed change" branches freely (eg to
update them to the current codebase) without permitting any damage to
the version branches "3.5", "3.6", "master", etc. In GitHub terms,
this is done by protecting a branch:

https://help.github.com/articles/about-protected-branches/

In a more directly-managed environment, this would be implemented with
a pre-receive or update hook:

https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

As this is a simple script, it has all the flexibility of code, so any
rule can be implemented.

>>Recommending "--no-commit" as the default makes the first flow longer
>>by adding a separate commit step without actually simplifying the
>>others.
>
> That's true, but I generally always want to review what git does before I
> publish it, and not committing makes that easier for me.
>
> The other thing is that there are lots of ways to accomplish things in git,
> and everyone will have their favorite workflow.  That's totally fine as long
> as things stay local.  It's okay to be opinionated and document the expected
> common good path, but most important is to document anything that will have
> global effects, because that affects everyone.   Maybe think about using words
> like MUST and SHOULD to delineate the difference (a la RFCs).

That would be a personal workflow choice, then. +1 on RFC 2119 MUST vs
SHOULD usage. IMO the document should specify *one* recommended
workflow, because otherwise it's just way too confusing to read; and
then by its language, it can clarify which parts you're allowed to
diverge from and which not.

Most of git _does_ stay local, and to the greatest extent possible,
the server should be set up to accept or reject commits that don't
comply with the workflow's MUSTs. If that central server is under
python.org's direct control, that simply means codifying all the MUSTs
into the pre-receive/update hook (see above), the code for which can
then be published alongside the workflow documents as a sort of
"clarifying document".

ChrisA