release_process.rst
246 lines
| 7.9 KiB
| text/x-rst
|
RstLexer
|
r22029 | .. _release_process: | ||
|
r22022 | |||
|
r22031 | ======================= | ||
IPython release process | ||||
======================= | ||||
|
r22022 | |||
|
r22029 | This document contains the process that is used to create an IPython release. | ||
|
r22022 | |||
|
r22668 | Conveniently, the ``release`` script in the ``tools`` directory of the ``IPython`` | ||
|
r22029 | repository automates most of the release process. This document serves as a | ||
|
r22714 | handy reminder and checklist for the release manager. | ||
During the release process, you might need the extra following dependencies: | ||||
- ``keyring`` to access your GitHub authentication tokens | ||||
- ``graphviz`` to generate some graphs in the documentation | ||||
|
r22717 | |||
Make sure you have all the required dependencies to run the tests as well. | ||||
|
r22714 | |||
|
r22029 | |||
|
r22030 | 1. Set Environment variables | ||
|
r22029 | ---------------------------- | ||
Set environment variables to document previous release tag, current | ||||
|
r22667 | release milestone, current release version, and git tag. | ||
|
r22022 | |||
|
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 | ||||
|
r22674 | ``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:: | ||||
|
r22667 | |||
PREV_RELEASE=4.2.1 | ||||
MILESTONE=5.0 | ||||
VERSION=5.0.0 | ||||
BRANCH=master | ||||
|
r22029 | |||
|
r22030 | 2. Create GitHub stats and finish release note | ||
---------------------------------------------- | ||||
|
r22029 | |||
.. note:: | ||||
|
r22022 | |||
|
r22667 | 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 | ||||
|
r23227 | <https://github.com/ipython/ipython/wiki/Dev:-GitHub-workflow#milestones>`_. | ||
|
r22667 | `This search | ||
<https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_ | ||||
|
r22029 | should return no results before creating the GitHub stats. | ||
|
r22022 | |||
|
r22029 | If a major release: | ||
|
r22022 | |||
|
r22029 | - merge any pull request notes into what's new:: | ||
|
r22022 | |||
python tools/update_whatsnew.py | ||||
|
r22667 | - update ``docs/source/whatsnew/development.rst``, to ensure it covers | ||
|
r22029 | the major release features | ||
|
r22667 | |||
|
r22668 | - move the contents of ``development.rst`` to ``versionX.rst`` where ``X`` is | ||
|
r22029 | the numerical release version | ||
|
r22667 | |||
|
r22029 | - generate summary of GitHub contributions, which can be done with:: | ||
|
r22022 | |||
|
r22029 | python tools/github_stats.py --milestone $MILESTONE > stats.rst | ||
|
r22022 | |||
|
r22667 | which may need some manual cleanup of ``stats.rst``. Add the cleaned | ||
``stats.rst`` results to ``docs/source/whatsnew/github-stats-X.rst`` | ||||
|
r22674 | where ``X`` is the numerical release version (don't forget to add it to | ||
the git repo 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. Finally, edit | ||||
``docs/source/whatsnew/index.rst`` to list the new ``github-stats-X`` | ||||
file you just created and remove temporarily the first entry called | ||||
``development`` (you'll need to add it back after release). | ||||
|
r22022 | |||
|
r22717 | Make sure that the stats file has a header or it won't be rendered in | ||
|
r22714 | the final documentation. | ||
|
r22030 | To find duplicates and update `.mailmap`, use:: | ||
|
r22022 | |||
|
r22029 | git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f | ||
|
r22022 | |||
|
r22032 | 3. Make sure the repository is clean | ||
------------------------------------ | ||||
|
r22022 | |||
|
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. | ||||
|
r22555 | 4. Update the release version number | ||
------------------------------------ | ||||
|
r22022 | |||
|
r22667 | Edit ``IPython/core/release.py`` to have the current version. | ||
|
r22022 | |||
|
r22032 | in particular, update version number and ``_version_extra`` content in | ||
``IPython/core/release.py``. | ||||
|
r22667 | Step 5 will validate your changes automatically, but you might still want to | ||
make sure the version number matches pep440. | ||||
|
r22032 | |||
|
r22667 | 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. | ||||
|
r22032 | |||
|
r22667 | You will likely just have to modify/comment/uncomment one of the lines setting | ||
``_version_extra`` | ||||
|
r22555 | 5. Run the `tools/build_release` script | ||
--------------------------------------- | ||||
|
r22667 | Running ``tools/build_release`` does all the file checking and building that | ||
|
r22555 | 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. | ||||
|
r22667 | The ``build_release`` script will in particular verify that the version number | ||
|
r22555 | 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 | ||||
------------------------------ | ||||
|
r22062 | Commit the changes to release.py:: | ||
|
r22022 | |||
git commit -am "release $VERSION" | ||||
git push origin $BRANCH | ||||
|
r22030 | Create and push the tag:: | ||
|
r22022 | |||
|
r22067 | git tag -am "release $VERSION" "$VERSION" | ||
|
r22022 | git push origin --tags | ||
|
r22667 | 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:: | ||||
|
r22022 | |||
git commit -am "back to development" | ||||
git push origin $BRANCH | ||||
|
r22555 | 7. Get a fresh clone | ||
|
r22029 | -------------------- | ||
|
r22022 | |||
|
r22030 | Get a fresh clone of the tag for building the release:: | ||
|
r22022 | |||
|
r22029 | cd /tmp | ||
|
r22067 | git clone --depth 1 https://github.com/ipython/ipython.git -b "$VERSION" | ||
|
r22667 | cd ipython | ||
.. note:: | ||||
You can aslo cleanup the current working repository with ``git clean -xfdi`` | ||||
|
r22022 | |||
|
r22555 | 8. Run the release script | ||
|
r22029 | ------------------------- | ||
|
r22022 | |||
|
r22667 | Run the ``release`` script, this step requires having a current wheel, Python | ||
>=3.4 and Python 2.7.:: | ||||
|
r22022 | |||
|
r22667 | ./tools/release | ||
|
r22022 | |||
|
r22667 | This makes the tarballs, zipfiles, and wheels, and put them under the ``dist/`` | ||
|
r22887 | 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. | ||||
|
r22032 | |||
|
r22667 | Use the following to actually upload the result of the build:: | ||
|
r22032 | |||
|
r22667 | ./tools/release upload | ||
|
r22022 | |||
|
r22667 | It should posts them to ``archive.ipython.org``. | ||
|
r22022 | |||
|
r22714 | You will need to use `twine <https://github.com/pypa/twine>`_ ) manually to | ||
actually upload on PyPI. Unlike setuptools, twine is able to upload packages | ||||
over SSL. | ||||
twine upload dist/* | ||||
|
r22032 | |||
|
r22667 | 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. | ||||
|
r22555 | 9. Draft a short release announcement | ||
|
r22029 | ------------------------------------- | ||
|
r22022 | |||
|
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) | ||||
|
r22022 | |||
|
r22032 | Post the announcement to the mailing list and or blog, and link from Twitter. | ||
|
r22029 | |||
|
r22667 | .. note:: | ||
If you are doing a RC or Beta, you can likely skip the next steps. | ||||
|
r22555 | 10. Update milestones on GitHub | ||
------------------------------- | ||||
|
r22029 | |||
|
r22030 | These steps will bring milestones up to date: | ||
|
r22029 | - close the just released milestone | ||
- open a new milestone for the next release (x, y+1), if the milestone doesn't | ||||
exist already | ||||
|
r22555 | 11. Update the IPython website | ||
|
r22032 | ------------------------------ | ||
|
r22030 | |||
|
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) | ||||
|
r22022 | |||
|
r22714 | 12. Update readthedocs | ||
---------------------- | ||||
Make sure to update readthedocs and set the latest tag as stable, as well as | ||||
|
r22717 | checking that previous release is still building under its own tag. | ||
|
r22714 | |||
|
r22717 | 13. Celebrate! | ||
|
r22030 | -------------- | ||
|
r22022 | |||
|
r22030 | Celebrate the release and please thank the contributors for their work. Great | ||
job! | ||||
|
r22022 | |||