Guide for IPython core Developers — IPython 9.2.0 documentation (original) (raw)

IPython release process

This document contains the process that is used to create an IPython release.

Conveniently, the release script in the tools directory of the IPythonrepository automates most of the release process. This document serves as a handy reminder and checklist for the release manager.

During the release process, you might need the extra following dependencies:

Make sure you have all the required dependencies to run the tests as well.

You can try to source tools/release_helper.sh when releasing via bash, it should guide you through most of the process.

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 toexport 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=main

For reproducibility of builds, we recommend setting SOURCE_DATE_EPOCH prior to running the build; record the used value of SOURCE_DATE_EPOCH as it may not be available from build artifact. You should be able to use date +%s to get a formatted timestamp:

SOURCE_DATE_EPOCH=$(date +%s)

2. Create GitHub stats and finish release note

Note

This step is optional if making a Beta or RC release.

Note

Before generating the GitHub stats, verify that all closed issues and pull requests have appropriate milestones.This searchshould return no results before creating the GitHub stats.

If a major release:

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:

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 inIPython/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 sdistand 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" -S git push origin $BRANCH

(omit the -S if you are no signing the package)

Create and push the tag:

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

(omit the -s if you are no signing the package)

Update release.py back to x.y-dev or x.y-maint commit and push:

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

(omit the -S if you are no signing the package)

Now checkout the tag we just made:

7. Run the release script

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

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.

Check the shasum of files with:

and takes notes of them you might need them to update the conda-forge recipes. Rerun the command and check the hash have not changed:

./tools/release shasum -a 256 dist/*

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

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:

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

Note

If you are doing a RC or Beta, you can likely skip the next steps.

9. Update milestones on GitHub

These steps will bring milestones up to date:

10. Update the IPython website

The IPython website should document the new 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!