Skip to content

Update release guide #16868

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 22, 2020
Merged

Update release guide #16868

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2413eb7
DOC: We use travis-ci.com now, not travis-ci.org.
QuLogic Mar 20, 2020
4811872
DOC: Update the release guide.
QuLogic Mar 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 87 additions & 60 deletions doc/devel/release_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ All Releases
Testing
-------

We use `travis-ci <https://travis-ci.org/matplotlib/matplotlib>`__ for
We use `Travis CI <https://travis-ci.org/matplotlib/matplotlib>`__ for
continuous integration. When preparing for a release, the final
tagged commit should be tested locally before it is uploaded::

Expand All @@ -34,7 +34,7 @@ tagged commit should be tested locally before it is uploaded::

In addition the following test should be run and manually inspected::

python unit/memleak.py agg agg.pdf
python tools/memleak.py agg 1000 agg.pdf


In addition the following should be run and manually inspected, but
Expand All @@ -51,42 +51,65 @@ GitHub Stats
------------


We automatically extract GitHub issue, PRs, and authors from GitHub via the API.
copy the current :file:`github_stats.rst` to :file:`github_stats_X.Y.Z.rst`.
We automatically extract GitHub issue, PRs, and authors from GitHub via the
API. Copy the current :file:`doc/users/github_stats.rst` to
:file:`doc/users/prev_whats_new/github_stats_X.Y.Z.rst`, changing the link
target at the top of the file, and removing the "Previous GitHub Stats" section
at the end.

To re-generate the updated ::
For example, when updating from v3.2.0 to v3.2.1::

python tools/github_stats.py --since-tag v2.2.0 --milestone=v3.0 --project 'matplotlib/matplotlib' --links > doc/users/github_stats.rst
cp doc/users/github_stats.rst doc/users/prev_whats_new/github_stats_3.2.0.rst
$EDITOR doc/users/prev_whats_new/github_stats_3.2.0.rst
# Change contents as noted above.
git add doc/users/prev_whats_new/github_stats_3.2.0.rst

Review and commit changes. Some issue/PR titles may not be valid rst (the most common issue is
``*`` which is interpreted as unclosed markup).
Then re-generate the updated stats::

.. note
python tools/github_stats.py --since-tag v3.2.0 --milestone=v3.2.1 --project 'matplotlib/matplotlib' --links > doc/users/github_stats.rst

Make sure you authenticate against the github API (either via
keyring or via putting an oauth token in :file:`~/.ghoauth`). If you
do not you will get blocked by github for going over the API rate
limits.
Review and commit changes. Some issue/PR titles may not be valid reST (the
most common issue is ``*`` which is interpreted as unclosed markup).

.. note::

Make sure you authenticate against the GitHub API. If you
do not you will get blocked by GitHub for going over the API rate
limits. You can authenticate in one of two ways:

* using the ``keyring`` package; ``pip install keyring`` and then when
running the stats script, you will be prompted for user name and password,
that will be stored in your system keyring, or,
* using a personal access token; generate a new token `on this GitHub page
<https://github.com/settings/tokens>`__ with the ``repo:public_repo``
scope and place the token in :file:`~/.ghoauth`.


.. _release_chkdocs:

Update and Validate the Docs
----------------------------

Merge the most recent 'doc' branch (``v3.0.2-doc``) into the branch you
Merge ``*-doc`` branch
^^^^^^^^^^^^^^^^^^^^^^

Merge the most recent 'doc' branch (e.g., ``v3.2.0-doc``) into the branch you
are going to tag on and delete the doc branch on GitHub.

Before tagging, update the "what's new" and "API changes" listings.
Update "What's New" and "API changes"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Before tagging major and minor releases, the "what's new" and "API changes"
listings should be updated. This is not needed for micro releases.

for the "what's new"
For the "what's new",

1. copy the current content to a file in :file:`doc/users/prev_whats_new`
2. merge all of the files in :file:`doc/users/next_whats_new/` into
:file:`doc/users/whats_new.rst` and delete the individual files
3. comment out the next whats new glob at the top

Similarly for the "API changes"
Similarly for the "API changes",

1. copy the current api changes to a file is :file:`doc/api/prev_api_changes`
2. merge all of the files in :file:`doc/api/next_api_changes/` into
Expand All @@ -95,13 +118,17 @@ Similarly for the "API changes"

In both cases step 3 will have to be un-done right after the release.

Verify that docs build
^^^^^^^^^^^^^^^^^^^^^^

Finally, make sure that the docs build cleanly ::

make -Cdoc O=-j$(nproc) html latexpdf

After the docs are built, check that all of the links, internal and external, are still
valid. We use ``linkchecker`` for this, which has not been ported to python3 yet. You will
need to create a python2 environment with ``requests==2.9.0`` and linkchecker ::
After the docs are built, check that all of the links, internal and external,
are still valid. We use ``linkchecker`` for this, which has not been ported to
Python3 yet. You will need to create a Python2 environment with
``requests==2.9.0`` and linkchecker ::

conda create -p /tmp/lnkchk python=2 requests==2.9.0
source activate /tmp/lnkchk
Expand All @@ -110,8 +137,8 @@ need to create a python2 environment with ``requests==2.9.0`` and linkchecker ::
linkchecker index.html --check-extern
popd

Address any issues which may arise. The internal links are checked on travis, this should only
flag failed external links.
Address any issues which may arise. The internal links are checked on Circle
CI, this should only flag failed external links.

.. _release_tag:

Expand All @@ -128,21 +155,21 @@ message ::

git tag -a -s v2.0.0

which will prompt you for your gpg key password and an annotation.
For pre releases it is important to follow :pep:`440` so that the
build artifacts will sort correctly in pypi. Finally, push the tag to GitHub ::

git push -t DANGER v2.0.0

Congratulations, the scariest part is done!
which will prompt you for your GPG key password and an annotation. For pre
releases it is important to follow :pep:`440` so that the build artifacts will
sort correctly in PyPI.

To prevent issues with any down-stream builders which download the
tarball from GitHub it is important to move all branches away from the commit
with the tag [#]_::

git commit --allow-empty
git push DANGER master

Finally, push the tag to GitHub::

git push DANGER master v2.0.0

Congratulations, the scariest part is done!

.. [#] The tarball that is provided by GitHub is produced using `git
archive <https://git-scm.com/docs/git-archive>`__. We use
Expand Down Expand Up @@ -170,8 +197,8 @@ done for pre-releases)::
git branch v2.0.0-doc
git push DANGER v2.0.0-doc

and if this is a major or minor release, also create a bug-fix branch (a
micro release will be cut off of this branch)::
and if this is a major or minor release, also create a bug-fix branch (a micro
release will be cut from this branch)::

git branch v2.0.x

Expand All @@ -192,31 +219,33 @@ Via the `GitHub UI
pushed tag into a release. If this is a pre-release remember to mark
it as such.

For final releases also get a DOI from `zenodo
<https://zenodo.org/>`__ and edit :file:`doc/citing.rst` with DOI link
and commit to the VER-doc branch and push to GitHub ::
For final releases, also get the DOI from `zenodo <https://zenodo.org/>`__
(which will automatically produce one once the tag is pushed), add the DOI link
to :file:`doc/citing.rst`, commit to the VER-doc branch and push to GitHub ::

git checkout v2.0.0-doc
emacs doc/_templates/citing.html
$EDITOR doc/citing.html
git push DANGER v2.0.0-doc:v2.0.0-doc

.. _release_bld_bin:

Building binaries
-----------------

We distribute mac, windows, and many linux wheels as well as a source
tarball via pypi. Before uploading anything, contact the various
builders. Mac and manylinux wheels are built on travis . You need to
edit the :file:`.travis.yml` file and push to the correct branch of
`the build project
<https://github.com/MacPython/matplotlib-wheels>`__. For new minor
versions create a new branch, for bug-fixes continue to use the current
release branch.

The auto-tick bot should open a pull request into the `conda-forge
feedstock <https://github.com/conda-forge/matplotlib-feedstock>`__.
Review and merge (if you have the power to).
We distribute macOS, Windows, and many Linux wheels as well as a source tarball
via PyPI. Most builders should trigger automatically once the tag is pushed to
GitHub:

* Mac and manylinux wheels are built on Travis CI. Builds are triggered by the
GitHub Action defined in :file:`.github/workflows/wheels.yml`, and wheels
will be available at the site defined in the `matplotlib-wheels repo
<https://github.com/MacPython/matplotlib-wheels>`__.
* Windows wheels are built by Christoph Gohlke automatically and will be
`available at his site
<https://www.lfd.uci.edu/~gohlke/pythonlibs/#matplotlib>`__ once built.
* The auto-tick bot should open a pull request into the `conda-forge feedstock
<https://github.com/conda-forge/matplotlib-feedstock>`__. Review and merge
(if you have the power to).

.. warning::

Expand All @@ -231,7 +260,6 @@ If this is a final release the following downstream packagers should be contacte
- Gentoo
- Macports
- Homebrew
- Christoph Gohlke
- Continuum
- Enthought

Expand All @@ -240,8 +268,8 @@ This can be done ahead of collecting all of the binaries and uploading to pypi.

.. _release_upload_bin:

make distribution and upload to pypi / SF
-----------------------------------------
Make distribution and upload to PyPI
------------------------------------

Once you have collected all of the wheels (expect this to take about a
day), generate the tarball ::
Expand Down Expand Up @@ -284,13 +312,12 @@ The built documentation exists in the `matplotlib.github.com
<https://github.com/matplotlib/matplotlib.github.com/>`__ repository.
Pushing changes to master automatically updates the website.

The documentation is organized by version. At the root of the tree is
always the documentation for the latest stable release. Under that,
there are directories containing the documentation for older versions.
The documentation for current master are built on travis and push to
the `devdocs <https://github.com/matplotlib/devdocs/>`__ repository.
These are available at `matplotlib.org/devdocs
<https://matplotlib.org/devdocs>`__.
The documentation is organized by version. At the root of the tree is always
the documentation for the latest stable release. Under that, there are
directories containing the documentation for older versions. The documentation
for current master is built on Circle CI and pushed to the `devdocs
<https://github.com/matplotlib/devdocs/>`__ repository. These are available at
`matplotlib.org/devdocs <https://matplotlib.org/devdocs>`__.

Assuming you have this repository checked out in the same directory as
matplotlib ::
Expand All @@ -314,7 +341,7 @@ You will need to manually edit :file:`versions.html` to show the last

Congratulations you have now done the third scariest part!

If you have access, clear the cloudflare caches.
If you have access, clear the Cloudflare caches.

It typically takes about 5-10 minutes for GitHub to process the push
and update the live web page (remember to clear your browser cache).
Expand All @@ -326,7 +353,7 @@ Announcing
The final step is to announce the release to the world. A short
version of the release notes along with acknowledgments should be sent to

- matplotlib-user@python.org
- matplotlib-users@python.org
- matplotlib-devel@python.org
- matplotlib-announce@python.org

Expand Down
4 changes: 2 additions & 2 deletions doc/devel/testing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ are in ``test_mathtext.py``.
Using Travis CI
---------------

`Travis CI <https://travis-ci.org/>`_ is a hosted CI system "in the
`Travis CI <https://travis-ci.com/>`_ is a hosted CI system "in the
cloud".

Travis is configured to receive notifications of new commits to GitHub
Expand All @@ -206,7 +206,7 @@ project.
Travis CI is already enabled for the `main Matplotlib GitHub
repository <https://github.com/matplotlib/matplotlib/>`_ -- for
example, see `its Travis page
<https://travis-ci.org/matplotlib/matplotlib>`_.
<https://travis-ci.com/matplotlib/matplotlib>`_.

If you want to enable Travis CI for your personal Matplotlib GitHub
repo, simply enable the repo to use Travis CI in either the Travis CI
Expand Down