release_process.rst
185 lines
| 5.8 KiB
| text/x-rst
|
RstLexer
Carol Willing
|
r22029 | .. _release_process: | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22031 | ======================= | ||
IPython release process | ||||
======================= | ||||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22029 | This document contains the process that is used to create an IPython release. | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22029 | Conveniently, the `release` script in the `tools` directory of the `IPython` | ||
repository automates most of the release process. This document serves as a | ||||
handy reminder and checklist for the release manager. | ||||
Carol Willing
|
r22030 | 1. Set Environment variables | ||
Carol Willing
|
r22029 | ---------------------------- | ||
Set environment variables to document previous release tag, current | ||||
Carol Willing
|
r22030 | release milestone, current release version, and git tag:: | ||
Carol Willing
|
r22022 | |||
PREV_RELEASE=rel-1.0.0 | ||||
MILESTONE=1.1 | ||||
VERSION=1.1.0 | ||||
TAG="rel-$VERSION" | ||||
BRANCH=master | ||||
Carol Willing
|
r22029 | 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` the variables. | ||||
Carol Willing
|
r22030 | 2. Create GitHub stats and finish release note | ||
---------------------------------------------- | ||||
Carol Willing
|
r22029 | |||
.. note:: | ||||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22029 | Before generating the GitHub stats, verify that all closed issues and | ||
Carol Willing
|
r22030 | pull requests have `appropriate milestones <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_. | ||
Carol Willing
|
r22029 | `This search <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_ | ||
should return no results before creating the GitHub stats. | ||||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22029 | If a major release: | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22029 | - merge any pull request notes into what's new:: | ||
Carol Willing
|
r22022 | |||
python tools/update_whatsnew.py | ||||
Carol Willing
|
r22029 | - 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:: | ||||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22029 | python tools/github_stats.py --milestone $MILESTONE > stats.rst | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22029 | 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. 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. | ||||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22030 | To find duplicates and update `.mailmap`, use:: | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22029 | git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f | ||
Carol Willing
|
r22022 | |||
Matthias Bussonnier
|
r22032 | 3. Make sure the repository is clean | ||
------------------------------------ | ||||
Carol Willing
|
r22022 | |||
Matthias Bussonnier
|
r22032 | of any file that could be problematic. | ||
Remove all non-tracked files with: | ||||
.. code:: | ||||
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. Run the `tools/build_release` script | ||||
Carol Willing
|
r22029 | --------------------------------------- | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22030 | 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. | ||||
Carol Willing
|
r22029 | |||
We encourage creating a test build of the docs as well. | ||||
Matthias Bussonnier
|
r22032 | 5. Create and push the new tag | ||
Carol Willing
|
r22029 | ------------------------------ | ||
Carol Willing
|
r22022 | |||
Edit `IPython/core/release.py` to have the current version. | ||||
Matthias Bussonnier
|
r22032 | in particular, update version number and ``_version_extra`` content in | ||
``IPython/core/release.py``. | ||||
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'. | ||||
Carol Willing
|
r22030 | Commit the changes to release.py and jsversion:: | ||
Carol Willing
|
r22022 | |||
git commit -am "release $VERSION" | ||||
git push origin $BRANCH | ||||
Carol Willing
|
r22030 | Create and push the tag:: | ||
Carol Willing
|
r22022 | |||
git tag -am "release $VERSION" "$TAG" | ||||
git push origin --tags | ||||
Carol Willing
|
r22030 | Update release.py back to `x.y-dev` or `x.y-maint`, and push:: | ||
Carol Willing
|
r22022 | |||
git commit -am "back to development" | ||||
git push origin $BRANCH | ||||
Matthias Bussonnier
|
r22032 | 6. Get a fresh clone | ||
Carol Willing
|
r22029 | -------------------- | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22030 | Get a fresh clone of the tag for building the release:: | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22029 | cd /tmp | ||
git clone --depth 1 https://github.com/ipython/ipython.git -b "$TAG" | ||||
Carol Willing
|
r22022 | |||
Matthias Bussonnier
|
r22032 | 7. Run the release script | ||
Carol Willing
|
r22029 | ------------------------- | ||
Carol Willing
|
r22022 | |||
Matthias Bussonnier
|
r22032 | Run the `release` script, this step requires having a current wheel, Python >=3.4 and Python 2.7.:: | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22029 | cd tools && ./release | ||
Carol Willing
|
r22022 | |||
Matthias Bussonnier
|
r22032 | This makes the tarballs, zipfiles, and wheels, and put them under the `dist/` | ||
folder. Be sure to test the ``wheel`` and the ``sdist`` locally before uploading | ||||
them to PyPI. | ||||
Use the following to actually upload the result of the build: | ||||
./release upload | ||||
Carol Willing
|
r22022 | |||
Matthias Bussonnier
|
r22032 | It should posts them to ``archive.ipython.org`` and registers the release | ||
with PyPI if you have the various authorisations. | ||||
Carol Willing
|
r22022 | |||
Matthias Bussonnier
|
r22032 | You might need to use `twine <https://github.com/pypa/twine>`_ (`twine upload | ||
dist/*`) manually to actually upload on PyPI. Unlike setuptools, twine is able | ||||
to upload packages over SSL. | ||||
8. Draft a short release announcement | ||||
Carol Willing
|
r22029 | ------------------------------------- | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22030 | 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) | ||||
Carol Willing
|
r22022 | |||
Matthias Bussonnier
|
r22032 | Post the announcement to the mailing list and or blog, and link from Twitter. | ||
Carol Willing
|
r22029 | |||
Matthias Bussonnier
|
r22032 | 9. Update milestones on GitHub | ||
Carol Willing
|
r22029 | ------------------------------ | ||
Carol Willing
|
r22030 | These steps will bring milestones up to date: | ||
Carol Willing
|
r22029 | - close the just released milestone | ||
- open a new milestone for the next release (x, y+1), if the milestone doesn't | ||||
exist already | ||||
Matthias Bussonnier
|
r22032 | 10. Update the IPython website | ||
------------------------------ | ||||
Carol Willing
|
r22030 | |||
Carol Willing
|
r22029 | 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) | ||||
Carol Willing
|
r22022 | |||
Matthias Bussonnier
|
r22032 | 11. Celebrate! | ||
Carol Willing
|
r22030 | -------------- | ||
Carol Willing
|
r22022 | |||
Carol Willing
|
r22030 | Celebrate the release and please thank the contributors for their work. Great | ||
job! | ||||
Carol Willing
|
r22022 | |||