Repository navigation
Doc release guide #6466
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.
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
Closed
Closed
Doc release guide #6466
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -6,27 +6,98 @@ Doing a matplotlib release | |
|
|
||
| A guide for developers who are doing a matplotlib release. | ||
|
|
||
| * Edit :file:`__init__.py` and bump the version number | ||
| Development (beta/RC) release checklist | ||
| --------------------------------------- | ||
|
|
||
| - [ ] Testing | ||
| - [ ] Create empty REL: commit | ||
| - [ ] Create tag | ||
| - [ ] Push tags + branches to GH | ||
| - [ ] Notify mac/windows/conda builders | ||
| - [ ] Merge everything to master | ||
| - [ ] announce release | ||
|
|
||
| Final release checklist | ||
| ----------------------- | ||
|
|
||
| - [ ] Testing | ||
| - [ ] update gh states | ||
| - [ ] Create empty REL: commit | ||
| - [ ] Create tag | ||
| - [ ] Create branches | ||
| - [ ] Push tags + branches to GH | ||
| - [ ] release / DOI management | ||
| - [ ] Notify mac/windows/conda builders | ||
| - [ ] Merge everything to master | ||
| - [ ] build documentation | ||
| - [ ] upload to pypi / sf | ||
| - [ ] deploy updated documentation | ||
| - [ ] announce release | ||
|
|
||
| Details | ||
| ------- | ||
|
|
||
| .. _release-testing: | ||
|
|
||
| Testing | ||
| ======= | ||
|
|
||
| * Run all of the regression tests by running ``python tests.py`` | ||
| at the root of the source tree. | ||
| 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:: | ||
|
|
||
| * Run :file:`unit/memleak_hawaii3.py` and make sure there are no | ||
| memory leaks | ||
| python tests.py --processes=8 --process-timeout=300 | ||
|
|
||
| * try some GUI examples, e.g., :file:`simple_plot.py` with GTKAgg, TkAgg, etc... | ||
| In addition :: | ||
|
|
||
| * remove font cache and tex cache from :file:`.matplotlib` and test | ||
| with and without cache on some example script | ||
| python unit/memleak_hawaii3.py | ||
|
|
||
| * Optionally, make sure :file:`examples/tests/backend_driver.py` runs | ||
| without errors and check the output of the PNG, PDF, PS and SVG | ||
| backends | ||
| should be run to check for memory leaks. Optionally, make sure :: | ||
|
|
||
| cd examples/tests/ | ||
| python backend_driver.py | ||
|
|
||
| runs without errors and check the output of the PNG, PDF, PS and SVG | ||
| backends. | ||
|
|
||
|
|
||
| .. _release_ghstats: | ||
|
|
||
| Github Stats | ||
| ============ | ||
|
|
||
| To make sure everyone's hard work gets credited, regenerate the github | ||
| stats. In the project root run :: | ||
|
|
||
| python tools/github_stats.py --since-tag $TAG --project 'matplotlib/matplotlib' --links > doc/users/github_stats.rst | ||
|
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. add note about editing to use pre-existing oath token |
||
|
|
||
|
|
||
| where `$TAG` is the tag of the last major release. This will generate | ||
| stats for all work done since that release. | ||
|
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. add note about installing requests + requests_cache |
||
|
|
||
| - [ ] review and commit changes | ||
| - [ ] check for valid rst | ||
| - [ ] re-add github-stats link | ||
|
|
||
| .. _release_tag: | ||
|
|
||
| Create Tag | ||
| ========== | ||
|
|
||
| On the tip of the current branch:: | ||
|
|
||
| git commit --allow-empty | ||
| git tag -a -s v1.5.0 | ||
|
|
||
| The commit and tag message should be very terse release notes should look something | ||
| like | ||
|
|
||
| REL: vX.Y.Z | ||
|
|
||
| Something brief description | ||
|
|
||
| Development releases should be post-fixed with the proper string following | ||
| `PEP 440<https://www.python.org/dev/peps/pep-0440/>`__ conventions. | ||
|
|
||
| .. _release-branching: | ||
|
|
||
|
|
@@ -40,27 +111,6 @@ the second part of the version number changes:: | |
| git checkout -b v1.1.x | ||
| git push git@github.com:matplotlib/matplotlib.git v1.1.x | ||
|
|
||
| On the branch, do any additional testing you want to do, and then build | ||
| binaries and source distributions for testing as release candidates. | ||
|
|
||
| For each release candidate as well as for the final release version, | ||
| please `git tag` the commit you will use for packaging like so:: | ||
|
|
||
| git tag -a v1.1.0rc1 | ||
|
|
||
| The `-a` flag will allow you to write a message about the tag, and | ||
| affiliate your name with it. A reasonable tag message would be something | ||
| like ``v1.1.0 Release Candidate 1 (September 24, 2011)``. To tag a | ||
| release after the fact, just track down the commit hash, and:: | ||
|
|
||
| git tag -a v1.0.1rc1 a9f3f3a50745 | ||
|
|
||
| Tags allow developers to quickly checkout different releases by name, | ||
| and also provides source download via zip and tarball on github. | ||
|
|
||
| Then push the tags to the main repository:: | ||
|
|
||
| git push upstream v1.0.1rc1 | ||
|
|
||
| .. _release-packaging: | ||
|
|
||
|
|
@@ -113,33 +163,27 @@ Then, to upload the source tarball:: | |
| rm -rf dist | ||
| python setup.py sdist upload | ||
|
|
||
| Documentation updates | ||
| ===================== | ||
|
|
||
| Build and deploy Documentation | ||
| ============================== | ||
|
|
||
| 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 | ||
| as well as the bleeding edge release version called `dev` (usually | ||
| based on what's on master in the github repository, but it may also | ||
| temporarily be a staging area for proposed changes). There is also a | ||
| symlink directory with the name of the most recently released version | ||
| that points to the root. With each new release, these directories may | ||
| need to be reorganized accordingly. Any time these version | ||
| directories are added or removed, the `versions.html` file (which | ||
| contains a list of the available documentation versions for the user) | ||
| must also be updated. | ||
| 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 `matplotlib.org/devdocs | ||
| <http://matplotlib.org/devdocs>`__. There is a symlink directory | ||
| with the name of the most recently released version that points to the | ||
| root. With each new release, these directories may need to be | ||
| reorganized accordingly. Any time these version directories are added | ||
| or removed, the `versions.html` file (which contains a list of the | ||
| available documentation versions for the user) must also be updated. | ||
|
|
||
| To make sure everyone's hard work gets credited, regenerate the github | ||
| stats. `cd` into the tools directory and run:: | ||
|
|
||
| python github_stats.py $TAG > ../doc/users/github_stats.rst | ||
|
|
||
| where `$TAG` is the tag of the last major release. This will generate | ||
| stats for all work done since that release. | ||
|
|
||
| In the matplotlib source repository, build the documentation:: | ||
|
|
||
|
|
@@ -160,6 +204,8 @@ changes upstream:: | |
| git commit -m "Updating for v1.0.1" | ||
| git push upstream master | ||
|
|
||
|
|
||
|
|
||
| Announcing | ||
| ========== | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we be running on Python 3 nowadays?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point. I normally work in a conda env so python is python3 (and most of my machines are arch so python is also python3) so I forget that is not universally the case.