DOC: lots of small fixes, add description of tarball issue

tacaswell · tacaswell · commit 74721f72a8df · 2016-12-18T10:53:49.000-05:00
diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst
@@ -24,18 +24,18 @@ tagged commit should be tested locally before it is uploaded::
 
 In addition the following two tests should be run and manually inspected::
 
-   python unit/memleak_hawaii3.py``
+   python unit/memleak_hawaii3.py
    pushd examples/tests/
    python backend_driver.py
    popd
 
 
 .. _release_ghstats:
 
-Github Stats
+GitHub Stats
 ------------
 
-We automatically extract github issue, PRs, and authors from the github via the API::
+We automatically extract GitHub issue, PRs, and authors from the GitHub via the API::
 
   python tools/github_stats.py --since-tag $TAG --project 'matplotlib/matplotlib' --links --milestone v2.0.0 > doc/users/github_stats.rst
 
@@ -50,12 +50,12 @@ Check Docs
 Before tagging, make sure that the docs build cleanly ::
 
   pushd doc
-  python make.py html pdf -n 16
+  python make.py html latex -n 16
   popd
 
 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 enviroment with ``requests==2.9.0`` and linkchecker ::
+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
@@ -82,20 +82,36 @@ 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 than the
-build artifacts will sort correctly in pypi.  Finally, push the tag to github ::
+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!
 
 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 ::
+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
 
+
+.. [#] The tarball that is provided by GitHub is produced using `git
+       archive <https://git-scm.com/docs/git-archive>`__.  We use
+       `versioneer <https://github.com/warner/python-versioneer>`__
+       which uses a format string in
+       :file:`lib/matplotlib/_version.py` to have ``git`` insert a
+       list of references to exported commit (see
+       :file:`.gitattributes` for the configuration).  This string is
+       then used by ``versioneer`` to produce the correct version,
+       based on the git tag, when users install from the tarball.
+       However, if there is a branch pointed at the tagged commit,
+       then the branch name will also be included in the tarball.
+       When the branch eventually moves, anyone how checked the hash
+       of the tarball before the branch moved will have an incorrect
+       hash.
+
 If this is a final release, also create a 'doc' branch (this is not
 done for pre-releases)::
 
@@ -110,18 +126,20 @@ micro release will be cut off of this branch)::
 
 
 
-.. _release_tag:
+.. _release_DOI:
 
 Release Management / DOI
 ------------------------
 
-Via the github UI (chase down link), turn the newly pushed tag into a
+Via the GitHub UI (chase down link), turn the newly 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/_templates/citing.html`
-with DOI link and commit to the VER-doc branch and push to github ::
+with DOI link and commit to the VER-doc branch and push to GitHub ::
 
+  git checkout v2.0.0-doc
+  emacs doc/_templates/citing.html
   git push DANGER v2.0.0-doc:v2.0.0-doc
 
 .. _release_bld_bin:
@@ -131,26 +149,25 @@ 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 master of `the build
+builders.  Mac and manylinux wheels are built on travis .  You need to
+edit the :file:`.travis.yml` file and push to master of `the build
 project <https://github.com/MacPython/matplotlib-wheels>`__.
 
 Update the ``master`` branch (for pre-releases the ``devel`` branch)
 of the `conda-forge feedstock
 <https://github.com/conda-forge/matplotlib-feedstock>`__ via pull request.
 
-If this is a final release the following down-steam packagers should be contacted:
+If this is a final release the following downsteam packagers should be contacted:
 
-- debian
-- fedora
-- arch
-- gentoo
-- macports
-- homebrew
+- Debian
+- Fedora
+- Arch
+- Gentoo
+- Macports
+- Homebrew
 - Christoph Gohlke
-- continuum
-- enthought
+- Continuum
+- Enthought
 
 This can be done ahead of collecting all of the binaries and uploading to pypi.
 
@@ -202,7 +219,7 @@ 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 `matplotlib.org/devdocs
+These are available at `matplotlib.org/devdocs
 <http://matplotlib.org/devdocs>`__.
 
 Assuming you have this repository checked out in the same directory as
@@ -211,23 +228,23 @@ matplotlib ::
   cd ../matplotlib.github.com
   mkdir 2.0.0
   rsync -a ../matplotlib/doc/build/html/* 2.0.0
-  cp ../matplotlib/doc/build/html/Matplotlib.pdf 2.0.0
+  cp ../matplotlib/doc/build/latex/Matplotlib.pdf 2.0.0
 
 which will copy the built docs over.  If this is a final release, also
 replace the top-level docs ::
 
   rsync -a 2.0.0/* ./
 
 You will need to manually edit :file:`versions.html` to show the last
-3 tagged versions.  Now commit and push everything to github ::
+3 tagged versions.  Now commit and push everything to GitHub ::
 
   git add *
   git commit -a -m 'Updating docs for v2.0.0
   git push DANGER master
 
 Congratulations you have now done the third scariest part!
 
-It typically takes about 5-10 minutes for github to process the push
+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).
 
 
@@ -244,7 +261,7 @@ version of the release notes along with acknowledgments should be sent to
 For final releases announcements should also be sent to the
 numpy/scipy/jupyter mailing lists and python-announce.
 
-In addition, annoucments should be made on social networks (twitter,
-g+, FB).  For major release, numFOCUS should be contacted for
-inclusion in their news letter and maybe to have something posted on
-their blog.
+In addition, announcements should be made on social networks (twitter,
+g+, FB).  For major release, `NumFOCUS <http://www.numfocus.org/>`__
+should be contacted for inclusion in their news letter and maybe to
+have something posted on their blog.
diff --git a/tools/github_stats.py b/tools/github_stats.py
@@ -77,15 +77,15 @@ def issues_closed_since(period=timedelta(days=365), project="ipython/ipython", p
         since = period
     url = "https://api.github.com/repos/%s/%s?state=closed&sort=updated&since=%s&per_page=%i" % (project, which, since.strftime(ISO8601), PER_PAGE)
     allclosed = get_paged_request(url, headers=make_auth_header())
-    
+
     filtered = [ i for i in allclosed if _parse_datetime(i['closed_at']) > since ]
     if pulls:
         filtered = [ i for i in filtered if _parse_datetime(i['merged_at']) > since ]
         # filter out PRs not against master (backports)
         filtered = [ i for i in filtered if i['base']['ref'] == 'master' ]
     else:
         filtered = [ i for i in filtered if not is_pull_request(i) ]
-    
+
     return filtered
 
 
@@ -113,10 +113,10 @@ def report(issues, show_urls=False):
     # deal with unicode
     if sys.version_info < (3,):
         sys.stdout = codecs.getwriter('utf8')(sys.stdout)
-    
+
     # Whether to add reST urls for all issues in printout.
     show_urls = True
-    
+
     parser = ArgumentParser()
     parser.add_argument('--since-tag', type=str,
         help="The git tag to use for the starting point (typically the last major release)."
@@ -133,10 +133,10 @@ def report(issues, show_urls=False):
     parser.add_argument('--links', action='store_true', default=False,
         help="Include links to all closed Issues and PRs in the output."
     )
-    
+
     opts = parser.parse_args()
     tag = opts.since_tag
-    
+
     # set `since` from days or git tag
     if opts.days:
         since = datetime.utcnow() - timedelta(days=opts.days)
@@ -153,9 +153,9 @@ def report(issues, show_urls=False):
             since += td
         else:
             since -= td
-    
+
     since = round_hour(since)
-    
+
     milestone = opts.milestone
     project = opts.project
 
@@ -172,18 +172,18 @@ def report(issues, show_urls=False):
     else:
         issues = issues_closed_since(since, project=project, pulls=False)
         pulls = issues_closed_since(since, project=project, pulls=True)
-    
+
     # For regular reports, it's nice to show them in reverse chronological order
     issues = sorted_by_field(issues, reverse=True)
     pulls = sorted_by_field(pulls, reverse=True)
-    
+
     n_issues, n_pulls = map(len, (issues, pulls))
     n_total = n_issues + n_pulls
-    
+
     # Print summary report we can directly include into release notes.
     print('.. _github-stats:')
     print()
-    print('Github Stats')
+    print('GitHub Stats')
     print('============')
 
     print()
@@ -193,18 +193,18 @@ def report(issues, show_urls=False):
     print()
     print("These lists are automatically generated, and may be incomplete or contain duplicates.")
     print()
-    
+
     ncommits = 0
     all_authors = []
     if tag:
         # print git info, in addition to GitHub info:
         since_tag = tag+'..'
         cmd = ['git', 'log', '--oneline', since_tag]
         ncommits += len(check_output(cmd).splitlines())
-        
+
         author_cmd = ['git', 'log', '--use-mailmap', "--format=* %aN", since_tag]
         all_authors.extend(check_output(author_cmd).decode('utf-8', 'replace').splitlines())
-    
+
     pr_authors = []
     for pr in pulls:
         pr_authors.extend(get_authors(pr))
@@ -219,12 +219,12 @@ def report(issues, show_urls=False):
         print("The full list can be seen `on GitHub <https://github.com/%s/milestone/%s>`__"
             % (project, milestone)
         )
-    
+
     print()
     print("The following %i authors contributed %i commits." % (len(unique_authors), ncommits))
     print()
     print('\n'.join(unique_authors))
-    
+
     if opts.links:
         print()
         print("GitHub issues and pull requests:")
