diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index ed1c6278e458..c287b92d135b 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -25,7 +25,7 @@ All Releases Testing ------- -We use `travis-ci `__ for +We use `Travis CI `__ for continuous integration. When preparing for a release, the final tagged commit should be tested locally before it is uploaded:: @@ -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 @@ -51,22 +51,38 @@ 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 + `__ with the ``repo:public_repo`` + scope and place the token in :file:`~/.ghoauth`. .. _release_chkdocs: @@ -74,19 +90,26 @@ Review and commit changes. Some issue/PR titles may not be valid rst (the most 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 @@ -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 @@ -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: @@ -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 `__. We use @@ -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 @@ -192,12 +219,12 @@ 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 -`__ 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 `__ +(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: @@ -205,18 +232,20 @@ and commit to the VER-doc branch and push to GitHub :: 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 -`__. 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 `__. -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 + `__. +* Windows wheels are built by Christoph Gohlke automatically and will be + `available at his site + `__ once built. +* The auto-tick bot should open a pull request into the `conda-forge feedstock + `__. Review and merge + (if you have the power to). .. warning:: @@ -231,7 +260,6 @@ If this is a final release the following downstream packagers should be contacte - Gentoo - Macports - Homebrew -- Christoph Gohlke - Continuum - Enthought @@ -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 :: @@ -284,13 +312,12 @@ The built documentation exists in the `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 `__ repository. -These are available at `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 +`__ repository. These are available at +`matplotlib.org/devdocs `__. Assuming you have this repository checked out in the same directory as matplotlib :: @@ -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). @@ -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 diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index c4d20bcda5e0..18944ff310b9 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -194,7 +194,7 @@ are in ``test_mathtext.py``. Using Travis CI --------------- -`Travis CI `_ is a hosted CI system "in the +`Travis CI `_ is a hosted CI system "in the cloud". Travis is configured to receive notifications of new commits to GitHub @@ -206,7 +206,7 @@ project. Travis CI is already enabled for the `main Matplotlib GitHub repository `_ -- for example, see `its Travis page -`_. +`_. 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