Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
148 changes: 97 additions & 51 deletions doc/devel/release_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copy link
Copy Markdown
Member

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?

Copy link
Copy Markdown
Member Author

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.


* 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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The 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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The 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:

Expand All @@ -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:

Expand Down Expand Up @@ -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::

Expand All @@ -160,6 +204,8 @@ changes upstream::
git commit -m "Updating for v1.0.1"
git push upstream master



Announcing
==========

Expand Down
10 changes: 4 additions & 6 deletions examples/tests/backend_driver.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@
subplots=os.path.join('..', 'subplots_axes_and_figures'),
specialty=os.path.join('..', 'specialty_plots'),
showcase=os.path.join('..', 'showcase'),
pylab=os.path.join('..', 'pylab_examples'),
pylab_examples=os.path.join('..', 'pylab_examples'),
api=os.path.join('..', 'api'),
units=os.path.join('..', 'units'),
mplot3d=os.path.join('..', 'mplot3d'))
Expand Down Expand Up @@ -107,9 +107,7 @@
'integral_demo.py',
]

files['pylab'] = [
'accented_text.py',
'alignment_test.py',
files['pylab_examples'] = [
'annotation_demo.py',
'annotation_demo.py',
'annotation_demo2.py',
Expand Down Expand Up @@ -444,7 +442,7 @@ def parse_options():
#epilog='\n'.join(doc[1:]) # epilog not supported on my python2.4 machine: JDH
)
op.disable_interspersed_args()
op.set_defaults(dirs='pylab,api,units,mplot3d',
op.set_defaults(dirs='pylab_examples,api,units,mplot3d',
clean=False, coverage=False, valgrind=False)
op.add_option('-d', '--dirs', '--directories', type='string',
dest='dirs', help=dedent('''
Expand Down Expand Up @@ -476,7 +474,7 @@ def parse_options():
valgrind=options.valgrind,
switches=switches)
if 'pylab_examples' in result.dirs:
result.dirs[result.dirs.index('pylab_examples')] = 'pylab'
result.dirs[result.dirs.index('pylab_examples')] = 'pylab_examples'
#print(result)
return (result)

Expand Down