##// END OF EJS Templates
Update changelog for 5.3
Update changelog for 5.3

File last commit:

r23414:939f7d61
r23429:382210e5
Show More
release_process.rst
239 lines | 7.7 KiB | text/x-rst | RstLexer
/ docs / source / coredev / release_process.rst
Carol Willing
Migrate the wiki contents to release process doc
r22029 .. _release_process:
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Update release process docs
r22031 =======================
IPython release process
=======================
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Migrate the wiki contents to release process doc
r22029 This document contains the process that is used to create an IPython release.
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
double backticks.
r22668 Conveniently, the ``release`` script in the ``tools`` directory of the ``IPython``
Carol Willing
Migrate the wiki contents to release process doc
r22029 repository automates most of the release process. This document serves as a
Matthias Bussonnier
Update release process instruction....
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
Matthias Bussonnier
Update release_process.rst
r22717
Make sure you have all the required dependencies to run the tests as well.
Matthias Bussonnier
Update release process instruction....
r22714
Carol Willing
Migrate the wiki contents to release process doc
r22029
Carol Willing
Fix up rst formatting
r22030 1. Set Environment variables
Carol Willing
Migrate the wiki contents to release process doc
r22029 ----------------------------
Set environment variables to document previous release tag, current
Matthias Bussonnier
Update release instruction...
r22667 release milestone, current release version, and git tag.
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Migrate the wiki contents to release process doc
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
Fernando Perez
Update release instructions for stats inclusion in whatsnew section.
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::
Matthias Bussonnier
Update release instruction...
r22667
PREV_RELEASE=4.2.1
MILESTONE=5.0
VERSION=5.0.0
BRANCH=master
Carol Willing
Migrate the wiki contents to release process doc
r22029
Carol Willing
Fix up rst formatting
r22030 2. Create GitHub stats and finish release note
----------------------------------------------
Carol Willing
Migrate the wiki contents to release process doc
r22029
.. note::
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Update release instruction...
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
Matthias Bussonnier
Backport PR #10184: Fix some broken links in the docs
r23227 <https://github.com/ipython/ipython/wiki/Dev:-GitHub-workflow#milestones>`_.
Matthias Bussonnier
Update release instruction...
r22667 `This search
<https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
Carol Willing
Migrate the wiki contents to release process doc
r22029 should return no results before creating the GitHub stats.
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Migrate the wiki contents to release process doc
r22029 If a major release:
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Migrate the wiki contents to release process doc
r22029 - merge any pull request notes into what's new::
Carol Willing
Add a core dev section to docs
r22022
python tools/update_whatsnew.py
Matthias Bussonnier
Update release instruction...
r22667 - update ``docs/source/whatsnew/development.rst``, to ensure it covers
Carol Willing
Migrate the wiki contents to release process doc
r22029 the major release features
Matthias Bussonnier
Update release instruction...
r22667
Matthias Bussonnier
double backticks.
r22668 - move the contents of ``development.rst`` to ``versionX.rst`` where ``X`` is
Carol Willing
Migrate the wiki contents to release process doc
r22029 the numerical release version
Matthias Bussonnier
Update release instruction...
r22667
Carol Willing
Migrate the wiki contents to release process doc
r22029 - generate summary of GitHub contributions, which can be done with::
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Migrate the wiki contents to release process doc
r22029 python tools/github_stats.py --milestone $MILESTONE > stats.rst
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Update release instruction...
r22667 which may need some manual cleanup of ``stats.rst``. Add the cleaned
``stats.rst`` results to ``docs/source/whatsnew/github-stats-X.rst``
Fernando Perez
Update release instructions for stats inclusion in whatsnew section.
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).
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Update release_process.rst
r22717 Make sure that the stats file has a header or it won't be rendered in
Matthias Bussonnier
Update release process instruction....
r22714 the final documentation.
Carol Willing
Fix up rst formatting
r22030 To find duplicates and update `.mailmap`, use::
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Migrate the wiki contents to release process doc
r22029 git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Consolidate the 2 files.
r22032 3. Make sure the repository is clean
------------------------------------
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Consolidate the 2 files.
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.
Matthias Bussonnier
Update release instructions....
r22555 4. Update the release version number
------------------------------------
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Update release instruction...
r22667 Edit ``IPython/core/release.py`` to have the current version.
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Consolidate the 2 files.
r22032 in particular, update version number and ``_version_extra`` content in
``IPython/core/release.py``.
Matthias Bussonnier
Update release instruction...
r22667 Step 5 will validate your changes automatically, but you might still want to
make sure the version number matches pep440.
Matthias Bussonnier
Consolidate the 2 files.
r22032
Matthias Bussonnier
Update release instruction...
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.
Matthias Bussonnier
Consolidate the 2 files.
r22032
Matthias Bussonnier
Update release instruction...
r22667 You will likely just have to modify/comment/uncomment one of the lines setting
``_version_extra``
Matthias Bussonnier
Update release instructions....
r22555 5. Run the `tools/build_release` script
---------------------------------------
Matthias Bussonnier
Update release instruction...
r22667 Running ``tools/build_release`` does all the file checking and building that
Matthias Bussonnier
Update release instructions....
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.
Matthias Bussonnier
Update release instruction...
r22667 The ``build_release`` script will in particular verify that the version number
Matthias Bussonnier
Update release instructions....
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
------------------------------
Thomas Kluyver
jsversion is no longer part of IPython
r22062 Commit the changes to release.py::
Carol Willing
Add a core dev section to docs
r22022
git commit -am "release $VERSION"
git push origin $BRANCH
Carol Willing
Fix up rst formatting
r22030 Create and push the tag::
Carol Willing
Add a core dev section to docs
r22022
Thomas Kluyver
Make release tags without rel- prefix...
r22067 git tag -am "release $VERSION" "$VERSION"
Carol Willing
Add a core dev section to docs
r22022 git push origin --tags
Matthias Bussonnier
Update release instruction...
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::
Carol Willing
Add a core dev section to docs
r22022
git commit -am "back to development"
git push origin $BRANCH
Matthias Bussonnier
Update release instructions....
r22555 7. Get a fresh clone
Carol Willing
Migrate the wiki contents to release process doc
r22029 --------------------
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Fix up rst formatting
r22030 Get a fresh clone of the tag for building the release::
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Migrate the wiki contents to release process doc
r22029 cd /tmp
Thomas Kluyver
Make release tags without rel- prefix...
r22067 git clone --depth 1 https://github.com/ipython/ipython.git -b "$VERSION"
Matthias Bussonnier
Update release instruction...
r22667 cd ipython
.. note::
Matthias Bussonnier
Backport PR #10241 on branch 5.x...
r23414 You can also cleanup the current working repository with ``git clean -xfdi``
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Update release instructions....
r22555 8. Run the release script
Carol Willing
Migrate the wiki contents to release process doc
r22029 -------------------------
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Update release instruction...
r22667 Run the ``release`` script, this step requires having a current wheel, Python
>=3.4 and Python 2.7.::
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Update release instruction...
r22667 ./tools/release
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Update release instruction...
r22667 This makes the tarballs, zipfiles, and wheels, and put them under the ``dist/``
Matthias Bussonnier
Backport PR #9873: Warn about universal wheels in the docs....
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.
Matthias Bussonnier
Consolidate the 2 files.
r22032
Matthias Bussonnier
Update release instruction...
r22667 Use the following to actually upload the result of the build::
Matthias Bussonnier
Consolidate the 2 files.
r22032
Matthias Bussonnier
Update release instruction...
r22667 ./tools/release upload
Carol Willing
Add a core dev section to docs
r22022
Matthias Bussonnier
Backport PR #10241 on branch 5.x...
r23414 It should posts them to ``archive.ipython.org`` and to PyPI.
Matthias Bussonnier
Consolidate the 2 files.
r22032
Matthias Bussonnier
Update release instruction...
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.
Matthias Bussonnier
Update release instructions....
r22555 9. Draft a short release announcement
Carol Willing
Migrate the wiki contents to release process doc
r22029 -------------------------------------
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Fix up rst formatting
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
Add a core dev section to docs
r22022
Matthias Bussonnier
Consolidate the 2 files.
r22032 Post the announcement to the mailing list and or blog, and link from Twitter.
Carol Willing
Migrate the wiki contents to release process doc
r22029
Matthias Bussonnier
Update release instruction...
r22667 .. note::
If you are doing a RC or Beta, you can likely skip the next steps.
Matthias Bussonnier
Update release instructions....
r22555 10. Update milestones on GitHub
-------------------------------
Carol Willing
Migrate the wiki contents to release process doc
r22029
Carol Willing
Fix up rst formatting
r22030 These steps will bring milestones up to date:
Carol Willing
Migrate the wiki contents to release process doc
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
Update release instructions....
r22555 11. Update the IPython website
Matthias Bussonnier
Consolidate the 2 files.
r22032 ------------------------------
Carol Willing
Fix up rst formatting
r22030
Carol Willing
Migrate the wiki contents to release process doc
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
Add a core dev section to docs
r22022
Matthias Bussonnier
Update release process instruction....
r22714 12. Update readthedocs
----------------------
Make sure to update readthedocs and set the latest tag as stable, as well as
Matthias Bussonnier
Update release_process.rst
r22717 checking that previous release is still building under its own tag.
Matthias Bussonnier
Update release process instruction....
r22714
Matthias Bussonnier
Update release_process.rst
r22717 13. Celebrate!
Carol Willing
Fix up rst formatting
r22030 --------------
Carol Willing
Add a core dev section to docs
r22022
Carol Willing
Fix up rst formatting
r22030 Celebrate the release and please thank the contributors for their work. Great
job!
Carol Willing
Add a core dev section to docs
r22022