DOC: update make_release document

Clean up with changes to various procedures.

Author: matthew-brett

doc/source/devel/make_release.rst

@@ -4,37 +4,29 @@
 A guide to making a nibabel release
 ***********************************
 
-A guide for developers who are doing a nibabel release
+This is a guide for developers who are doing a nibabel release.
 
 .. _release-tools:
 
 Release tools
 =============
 
-There are some release utilities that come with nibabel_.  nibabel should
-install these as the ``nisext`` package, and the testing stuff is understandably
-in the ``testers`` module of that package.  nibabel has Makefile targets for their
-use.  The relevant targets are::
+There are some release utilities that come with nibabel.  nibabel should
+install these as the ``nisext`` package, and the testing stuff is
+understandably in the ``testers`` module of that package.  nibabel has
+Makefile targets for their use.  The relevant targets are::
 
     make check-version-info
     make check-files
     make sdist-tests
 
 The first installs the code from a git archive, from the repository, and for
-in-place use, and runs the ``get_info()`` function to confirm that installation
-is working and information parameters are set correctly.
+in-place use, and runs the ``get_info()`` function to confirm that
+installation is working and information parameters are set correctly.
 
 The second (``sdist-tests``) makes an sdist source distribution archive,
 installs it to a temporary directory, and runs the tests of that install.
 
-If you have a version of nibabel trunk past February 11th 2011, there will also
-be a functional make target::
-
-    make bdist-egg-tests
-
-This builds an egg (which is a zip file), hatches it (unzips the egg) and runs
-the tests from the resulting directory.
-
 .. _release-checklist:
 
 Release checklist
@@ -47,17 +39,17 @@ Release checklist
 * Review and update the release notes.  Review and update the ``Changelog``
   file.  Get a partial list of contributors with something like::
 
-      git log 1.3.0.. | grep '^Author' | cut -d' ' -f 2- | sort | uniq
+      git log 2.0.0.. | grep '^Author' | cut -d' ' -f 2- | sort | uniq
 
-  where ``1.3.0`` was the last release tag name.
+  where ``2.0.0`` was the last release tag name.
 
-  Then manually go over ``git shortlog 1.2.0..`` to make sure the release notes
-  are as complete as possible and that every contributor was recognized.
+  Then manually go over ``git shortlog 2.0.0..`` to make sure the release
+  notes are as complete as possible and that every contributor was recognized.
 
 * Look at ``doc/source/index.rst`` and add any authors not yet acknowledged.
 
-* Update thanks to authors in ``doc/source/index.rst`` and consider any
-  updates to the ``AUTHOR`` file.
+* Update new authors and add thansk in ``doc/source/index.rst`` and consider
+  any updates to the ``AUTHOR`` file.
 
 * Use the opportunity to update the ``.mailmap`` file if there are any
   duplicate authors listed from ``git shortlog -nse``.
@@ -75,26 +67,26 @@ Release checklist
 
 * Check the dependencies listed in ``nibabel/info.py`` (e.g.
   ``NUMPY_MIN_VERSION``) and in ``doc/source/installation.rst``.  They should
-  at least match. Do they still hold?
+  at least match. Do they still hold?  Make sure `nibabel on travis`_ is
+  testing the minimum dependencies specifically.
 
-* Do a final check on the `nipy buildbot`_
+* Do a final check on the `nipy buildbot`_.  Use the ``try_branch.py``
+  scheduler available in nibotmi_ to test particular schedulers.
 
-* If you have travis-ci_ building set up you might want to push the code in it's
-  current state to a branch that will build, e.g::
+* If you have travis-ci_ building set up for your own repo you might want to
+  push the code in it's current state to a branch that will build, e.g::
 
     git branch -D pre-release-test # in case branch already exists
     git co -b pre-release-test
-    git push origin pre-release-test
+    git push your-github-user pre-release-test -u
 
 * Clean::
 
     make distclean
 
 * Make sure all tests pass (from the nibabel root directory)::
 
-    cd ..
     nosetests --with-doctest nibabel
-    cd nibabel # back to the root directory
 
 * Make sure all tests pass from sdist::
 
@@ -122,7 +114,8 @@ Release checklist
 
     Missed script files:  /Users/mb312/dev_trees/nibabel/bin/nib-dicomfs, /Users/mb312/dev_trees/nibabel/bin/nifti1_diagnose.py
 
-  Fix ``setup.py`` to carry across any files that should be in the distribution.
+  Fix ``setup.py`` to carry across any files that should be in the
+  distribution.
 
 * You probably have virtualenvs for different Python versions.  Check the
   tests pass for different configurations. The long-hand way looks like this::
@@ -143,6 +136,8 @@ Release checklist
     make doctest
     cd ..
 
+  This should also be tested by `nibabel on travis`_.
+
 * Check everything compiles without syntax errors::
 
     python -m compileall .
@@ -175,28 +170,28 @@ Release checklist
     python setup.py register
     python setup.py sdist --formats=gztar,zip upload
 
-* Tag the release with tag of form ``1.4.0``::
+* Tag the release with tag of form ``2.0.0``::
 
-    git tag -am 'Fourth main release' 1.4.0
+    git tag -am "Something about this release' 2.0.0
 
 * Push the tag and any other changes to trunk with::
 
     git push --tags
 
 * Force builds of the win32 and amd64 binaries from the buildbot. Go to pages:
 
-  * http://nipy.bic.berkeley.edu/builders/nibabel-bdist32
-  * http://nipy.bic.berkeley.edu/builders/nibabel-bdist64
+  * http://nipy.bic.berkeley.edu/builders/nibabel-bdist32-27
+  * http://nipy.bic.berkeley.edu/builders/nibabel-bdist32-34
+  * http://nipy.bic.berkeley.edu/builders/nibabel-bdist64-27
 
-  For each of these, enter the revision number (e.g. "1.4.0") in the field
+  For each of these, enter the revision number (e.g. "2.0.0") in the field
   "Revision to build". Then get the built binaries in:
 
-  * http://nipy.bic.berkeley.edu/dist-32
-  * http://nipy.bic.berkeley.edu/dist-64
+  * http://nipy.bic.berkeley.edu/nibabel-dist
 
-  and upload them to pypi with the admin files interface, or using twine_.
+  and upload them to pypi with the admin files interface.
 
-  If you are already on a windows machine, you could have done the manual
+  If you are already on a Windows machine, you could have done the manual
   command to upload instead: ``python setup.py bdist_wininst upload``.
 
 * Now the version number is OK, push the docs to sourceforge with::
@@ -213,35 +208,37 @@ Release checklist
 
   * Branch to maintenance::
 
-      git co -b maint/1.0.x
+      git co -b maint/2.0.x
 
     Set ``_version_extra`` back to ``.dev`` and bump ``_version_micro`` by 1.
-    Thus the maintenance series will have version numbers like - say - '1.0.1.dev'
-    until the next maintenance release - say '1.0.1'.  Commit. Don't forget to
-    push upstream with something like::
+    Thus the maintenance series will have version numbers like - say -
+    '2.0.1.dev' until the next maintenance release - say '2.0.1'.  Commit.
+    Don't forget to push upstream with something like::
 
-      git push upstream maint/1.0.0 --set-upstream
+      git push upstream-remote maint/2.0.x --set-upstream
 
   * Start next development series::
 
       git co main-master
 
-    then restore ``.dev`` to ``_version_extra``, and bump ``_version_minor`` by 1.
-    Thus the development series ('trunk') will have a version number here of
-    '1.1.0.dev' and the next full release will be '1.1.0'.
+    then restore ``.dev`` to ``_version_extra``, and bump ``_version_minor``
+    by 1.  Thus the development series ('trunk') will have a version number
+    here of '2.1.0.dev' and the next full release will be '2.1.0'.
+
+    Next merge the maintenace branch with the "ours" strategy.  This just
+    labels the maintenance `info.py` edits as seen but discarded, so we can
+    merge from maintenance in future without getting spurious merge
+    conflicts::
 
-    Next merge the maintenace branch with the "ours" strategy.  This just labels
-    the maintenance `info.py` edits as seen but discarded, so we can merge from
-    maintenance in future without getting spurious merge conflicts::
+       git merge -s ours maint/2.0.x
 
-       git merge -s ours maint/1.3.x
 
-  If this is just a maintenance release from ``maint/1.0.x`` or similar, just
-  tag and set the version number to - say - ``1.0.2.dev``.
+  If this is just a maintenance release from ``maint/2.0.x`` or similar, just
+  tag and set the version number to - say - ``2.0.2.dev``.
 
 * Push the main branch::
 
-    git push main-master
+    git push upstream-remote main-master
 
 * Make next development release tag
 
@@ -253,16 +250,14 @@ Release checklist
 
     This tag is used in the Makefile rules to create development snapshot
     releases to create proper versions for those. The version derives its name
-    from the last available annotated tag, the number of commits since that, and
-    an abbreviated SHA1. See the docs of ``git describe`` for more info.
+    from the last available annotated tag, the number of commits since that,
+    and an abbreviated SHA1. See the docs of ``git describe`` for more info.
 
-    Please take a look at the Makefile rules ``devel-src``,
-    ``devel-dsc`` and ``orig-src``.
+    Please take a look at the Makefile rules ``devel-src``, ``devel-dsc`` and
+    ``orig-src``.
 
 * Announce to the mailing lists.
 
-.. _pytox: http://codespeak.net/tox
 .. _setuptools intro: http://packages.python.org/an_example_pypi_project/setuptools.html
-.. _travis-ci: http://travis-ci.org
 
 .. include:: ../links_names.txt

doc/source/links_names.txt

@@ -20,6 +20,7 @@
 .. _nibabel issues: http://github.com/nipy/nibabel/issues
 .. _nibabel github issues: http://github.com/nipy/nibabel/issues
 .. _nibabel wiki: https://github.com/nipy/nibabel.wiki
+.. _nibabel on travis: http://travis-ci.org/nipy/nibabel
 
 .. other related projects
 .. _nipy community: http://nipy.org
@@ -31,8 +32,8 @@
 .. _nipy development guidelines: http://nipy.org/devel
 .. _`nipy github`: http://github.com/nipy/nipy
 .. _nipy buildbot: http://nipy.bic.berkeley.edu
-.. _nibabel on travis: http://travis-ci.org/nipy/nibabel
 .. _travis-ci: http://travis-ci.org
+.. _nibotmi: https://github.com/nipy/nibotmi
 
 .. Documentation tools
 .. _graphviz: http://www.graphviz.org/