Backporting Pull requests

All pull requests should usually be made against master, if a Pull Request need to be backported to an earlier release; then it should be tagged with the correct milestone.

If you tag a pull request with a milestone before merging the pull request, and the base ref is master, then our backport bot should automatically create a corresponding pull-request that backport on the correct branch.

If you are an admin on the IPython repository you can also just mention the backport bot to do the work for you. The bot is evolving so instructions may be different. At the time of this writing you can use:

@meeseeksdev[bot] backport [to <branchname>]

The bot will attempt to backport the current pull-request and issue a PR if possible. If the milestone is set on the issue you can omit the branch to backport to.

If the pull request cannot be automatically backported, the bot should tell you so on the PR and apply a "Need manual backport" tag to the origin PR.

Backport with ghpro

We can also use ghpro <https://pypi.python.org/pypi/ghpro> to automatically list and apply the PR on other branches. For example:

$ backport-pr todo --milestone 5.2
[...snip..]
The following PRs have been backported
9848
9851
9953
9955
The following PRs should be backported:
9417
9863
9925
9947

$ backport-pr apply 5.x 9947
[...snip...]

1. Set Environment variables

Set environment variables to document previous release tag, current release milestone, current release version, and git tag.

These variables may be used later to copy/paste as answers to the script questions instead of typing the appropriate command when the time comes. These variables are not used by the scripts directly; therefore, there is no need to export them. The format for bash is as follows, but note that these values are just an example valid only for the 5.0 release; you'll need to update them for the release you are actually making:

PREV_RELEASE=4.2.1
MILESTONE=5.0
VERSION=5.0.0
BRANCH=master

2. Create GitHub stats and finish release note

If a major release:

• merge any pull request notes into what's new:

  python tools/update_whatsnew.py
  

• update docs/source/whatsnew/development.rst, to ensure it covers the major release features

• move the contents of development.rst to versionX.rst where X is the numerical release version

• generate summary of GitHub contributions, which can be done with:

  python tools/github_stats.py --milestone $MILESTONE > stats.rst
  

  which may need some manual cleanup of stats.rst. Add the cleaned stats.rst results to docs/source/whatsnew/github-stats-X.rst where X is the numerical release version (don't forget to add it to the git repository as well). If creating a major release, make a new github-stats-X.rst file; if creating a minor release, the content from stats.rst may simply be added to the top of an existing github-stats-X.rst file.

• Edit docs/source/whatsnew/index.rst to list the new github-stats-X file you just created.

• Remove temporarily the first entry called development (you'll need to add it back after release).

  Make sure that the stats file has a header or it won't be rendered in the final documentation.

To find duplicates and update .mailmap, use:

git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f

If a minor release you might need to do some of the above points manually, and forward port the changes.

3. Make sure the repository is clean

of any file that could be problematic.

Remove all non-tracked files with:

git clean -xfdi

This will ask for confirmation before removing all untracked files. Make sure the dist/ folder is clean to avoid any stale builds from previous build attempts.

4. Update the release version number

Edit IPython/core/release.py to have the current version.

in particular, update version number and _version_extra content in IPython/core/release.py.

Step 5 will validate your changes automatically, but you might still want to make sure the version number matches pep440.

In particular, rc and beta are not separated by . or the sdist and bdist will appear as different releases. For example, a valid version number for a release candidate (rc) release is: 1.3rc1. Notice that there is no separator between the '3' and the 'r'. Check the environment variable $VERSION as well.

You will likely just have to modify/comment/uncomment one of the lines setting _version_extra

5. Run the tools/build_release script

Running tools/build_release does all the file checking and building that the real release script will do. This makes test installations, checks that the build procedure runs OK, and tests other steps in the release process.

The build_release script will in particular verify that the version number match PEP 440, in order to avoid surprise at the time of build upload.

We encourage creating a test build of the docs as well.

6. Create and push the new tag

Commit the changes to release.py:

git commit -am "release $VERSION"
git push origin $BRANCH

Create and push the tag:

git tag -am "release $VERSION" "$VERSION"
git push origin --tags

Update release.py back to x.y-dev or x.y-maint, and re-add the development entry in docs/source/whatsnew/index.rst and push:

git commit -am "back to development"
git push origin $BRANCH

Now checkout the tag we just made:

git checkout $VERSION

7. Run the release script

Run the release script, this step requires having a current wheel, Python >=3.4 and Python 2.7.:

./tools/release

This makes the tarballs and wheels, and puts them under the dist/ folder. Be sure to test the wheels and the sdist locally before uploading them to PyPI. We do not use an universal wheel as each wheel installs an ipython2 or ipython3 script, depending on the version of Python it is built for. Using an universal wheel would prevent this.

Use the following to actually upload the result of the build:

./tools/release upload

It should posts them to archive.ipython.org and to PyPI.

PyPI/Warehouse will automatically hide previous releases. If you are uploading a non-stable version, make sure to log-in to PyPI and un-hide previous version.

8. Draft a short release announcement

The announcement should include:

• release highlights
• a link to the html version of the What's new section of the documentation
• a link to upgrade or installation tips (if necessary)

Post the announcement to the mailing list and or blog, and link from Twitter.

9. Update milestones on GitHub

These steps will bring milestones up to date:

• close the just released milestone
• open a new milestone for the next release (x, y+1), if the milestone doesn't exist already

10. Update the IPython website

The IPython website should document the new release:

• add release announcement (news, announcements)
• update current version and download links
• update links on the documentation page (especially if a major release)

11. Update readthedocs

Make sure to update readthedocs and set the latest tag as stable, as well as checking that previous release is still building under its own tag.

12. Update the Conda-Forge feedstock

Follow the instructions on the repository

13. Celebrate!

Celebrate the release and please thank the contributors for their work. Great job!