ADMIN: backports branch

[jreback]

As discussed on the mailing list, we should outline how we are going to do backports. Goals would be to provide a 0.19.1 bug-fix only release and at the same time allow master to proceed as 0.20/1.0 with all bug-fixes and API changes.

This issue is for how to do this, as we are ready to merge some 0.19.1 fixes. So need to put some machinery in place ASAP.

• create a 0.19.1 (or .x?) branch
• scripts/merge-py.py merges to master
• then cherry-pick to 0.19.1?

Some questions

• how to ensure that we are getting the appropriate commits. Do we need a comparison script?
• how do we deal with the duplicated whatsnew issue (IOW, should commiters be directed to 0.20, then we copy / fix to put also in 0.19.1)?
• testing, I think travis/appveyor will build both branches (master and 0.19.x)

would be nice to link some examples of how other projects do this. We have quite a lot of activity and don't want this to become a burden.

[jreback]

@jorisvandenbossche @wesm @sinhrks @shoyer @TomAugspurger @chris-b1

[TomAugspurger]

Thanks for raising this Jeff. I think we should start a "Needs backport" label, or maybe version that like "Backport 0.19" for all PRs that should be backported.

I don't think anything changes from the contributors POV, right? All PRs should still go against master. Release notes are the bit I'm not sure about. Will the 0.20 notes be as if it's 0.19 -> 0.20, or 0.19.x -> 0.20?

Some links

• NumPy / Scipy
  • PR is merged to master
  • maintainer branches off 0.19.1
  • cherry-picks the commits (resolves conflicts)
  • push a new PR against 0.19.1
• this recommends the -x flag for cherry pick to add info on where the commits where cherry picked from
• Django has a script here, could be useful

[TomAugspurger]

One other thing, will we need the doc build script to only push if it's a PR against master? Don't want http://pandas-docs.github.io/pandas-docs-travis/ to jump between 0.20 and 0.19.1 depending on the latest PR merged.

[jorisvandenbossche]

Well, I was looking how other project do this:

• Numpy merges to master, and for each commit that needs to be backported another PR is made to merge into the maintenance branch (eg Backport 8028, DOC: Update 1.11.2 release notes. numpy/numpy#8032). As @TomAugspurger linked to, the workflow is described here: http://docs.scipy.org/doc/numpy-1.10.4/dev/gitwash/development_workflow.html#backporting
  • I didn't find any scripts to automate this
  • What makes it more simple in their case is that they generally do not include any whatsnew notices in each commit
• scikit-learn also always merges to master, but does not necessarily make a PR for each backport.
  • I saw in some cases they ask people to put the whatsnew in eg the 0.19.1 file in the original PR, because they plan to backport it (eg [MRG+1] Fix reading of Bunch pickles that have been generated with scikit-learn < 0.17 scikit-learn/scikit-learn#6235)

Matplotlib has a different approach according to [their wiki](https://github.com/matplotlib/matplotlib/wiki#developer-info, but I don't know if that is up to date with their actual workflow): bug fixes go in 1.5.x and regularly 1.5.x is merged in 2.0.x and then 2.0.x in master. This seems a lot more complex to me (and if you forget a backport, then it is master that is not up to date, while in the "everything is first merged in master" approach, it is the maintenance branch that can miss something, which seems less serious to me)

Thanks for raising this Jeff. I think we should start a "Needs backport" label, or maybe version that like "Backport 0.19" for all PRs that should be backported.

I don't think we need a "Backport 0.19" label, as we have a 0.19.1 Milestone to indicate if a PR is supposed to be included in the maintenance branch. A "need backport" label can of course help to track the ones that still needs to be backported.

how do we deal with the duplicated whatsnew issue (IOW, should commiters be directed to 0.20, then we copy / fix to put also in 0.19.1)?

One option would go with the approach of putting it directly in the 0.19.1 file. So if we decide that a PR is suited for 0.19.1, we tag it like that, and the whatsnew note is added to the 0.19.1 file. It is then merged like this to master. The advantage is a) you don't need to adapt the commit when backporting (changing the whatsnew location) and b) the master docs are already up to date with when a bug fix was released.
Of course at a certain point in time (eg after 0.19.1 is released), it will not be clear up front if there is coming another bugfix release. In that case we can maybe deviate from this workflow.

testing, I think travis/appveyor will build both branches (master and 0.19.x)

This is indeed not a problem I think, travis already tests other branches than master.

[jorisvandenbossche]

To summarize my above long comment, I would propose we try the following workflow:

• For an issue/PR: discuss if it should go into a bug fix release, and if so: tag it with the appropriate milestone (in this case: 0.19.1)
• PR tagged with 0.19.1 still targets master, but is written as it is for 0.19.1 (whatsnew notice in the 0.19.1 file, mentioning this release number where needed)
• PR is merged into master
• The one resulting commit of the PR is backported to the 0.19.x branch using cherry-pick
  • fix conflicts when needed (certainly in the beginning (if master has not yet changed a lot), in most cases there will be no conflicts)
• Open question: make a PR of this cherry-picked commit or directly commit to the 0.19.x branch?
  • The numpy approach of making a PR of each backport with consistent title ("Backport #xxxx ...") makes it more transparant, but also increases the number of PRs on github even further.

The last step could be automated (similar to the merge-pr.py script), but I think we can first try to see if this works (not needed to already have an automation script now to start with a 0.19.x branch).
In the same sense, we can later look at ways to automatically check that all tagged PRs are actually backported.

[TomAugspurger]

The astropy docs seem useful as well (similar workflow).

I don't think we need a "Backport 0.19" label, as we have a 0.19.1 Milestone to indicate if a PR is supposed to be included in the maintenance branch.

Sounds good. It's too bad we can't assign multiple milestones to an issue / PR, but I'm guessing almost all bug fixes will apply to both 0.19.x and 0.20, so this won't be a big deal in practice.

[jorisvandenbossche]

Any other feedback or comments on the proposed workflow? (#14352 (comment))

[wesm]

This seems fine to me. I don't think having additional backport PRs is necessary right now unless we have issues with failing builds after cherry-pick.

[tacaswell]

Also see http://matplotlib.org/devdocs/devel/coding_guide.html?highlight=review#backports

[jreback]

@jorisvandenbossche did you document this procedure anywhere (on wiki)?

[jorisvandenbossche]

To summarize how the procedure went for 0.19.x:

• Everything is merged in master:
  • For an issue/PR: discuss if it should go into a bug fix release, and if so: tag it with the appropriate milestone (in this case: 0.19.1)
  • PR tagged with 0.19.1 still targets master, but is written as it is for 0.19.1 (whatsnew notice in the 0.19.1 file, mentioning this release number where needed)
  • PR is merged into master
• Backport to 0.19.x branch:

  • The one resulting commit of the PR is backported to the 0.19.x branch using cherry-pick and fix conflicts when needed (in practice this was almost never needed for the 0.19.x releases). So I mainly did:

    git checkout 0.19.x
    git cherry-pick ..commit-sha..
    

  • In practice, what I did was the following:

    • Go through the history of master (from where 0.19.x was branched to more recent), check for each commit whether it needs backporting (based on tag of connected PR, at once extra check this tagging was actually correct based), and if so copy sha and cherry-pick it.
    • I did this a couple times for a whole bunch at once, and you can just check the latest commit in the 0.19.x branch where you left off the previous time.

I also had a script that could automate this a little bit, but in practice it didn't give much value above using the cherry-pick (you could give the PR number instead of the commit sha). But in theory, we could write a script that gets all PRs, check that they were tagged with the specific release, and cherry-pick them in order, to automate this (supposing all changes went through PRs). But not sure this is worth the effort. What I used then is here: https://gist.github.com/jorisvandenbossche/e97c22f7176180a5548f767e520586bb#file-backport-pr-py-L113-L126

[jreback]

@jorisvandenbossche added your text to: https://github.com/pandas-dev/pandas/wiki/Backporting

thanks!

[jorisvandenbossche]

Due to branch for bugfix releases, we have the issue that master version is smaller than released version: #15156

Proposed solution (from discussion in https://gitter.im/pydata/pandas?at=58e6b4610e4137042aee7e86): after branching the bugfix release branch (eg 0.20.x), tag master with the 0.21.0.dev (or 0.20.dev) tag.
This should then give the correct order of versions (https://www.python.org/dev/peps/pep-0440/#developmental-releases): eg 0.19.2 < 0.20.0.dev < 0.20.0rc < 0.20.0

[jreback]

documented nicely by @jorisvandenbossche and @TomAugspurger