DOC - update release instructions; link to developer docs

Author: matthew-brett

doc/source/devel/index.rst

@@ -1,9 +1,14 @@
 .. -*- mode: rst -*-
 .. ex: set sts=4 ts=4 sw=4 et tw=79:
 
+.. _devindex:
+
+Developer documentation page
+============================
+
 .. toctree::
-   :hidden:
+    :maxdepth: 2
 
-   devguide
-   devdiscuss
-   make-release
+    devguide
+    devdiscuss
+    make-release

doc/source/devel/make-release.rst

@@ -8,35 +8,41 @@ A guide for developers who are doing a nibabel release
 
 * Edit :file:`info.py` and bump the version number
 
-.. _release-tools::
+.. _release-tools:
 
 Release tools
 =============
 
-In :file:`nibabel/tools`, among other files, you will find
-the following utilities::
+In the :file:`tools` directory, among other files, you will find the following
+utilities::
 
-    nibabel/tools/
+    tools/
     |- build_release
     |- release
     |- compile.py
     |- make_tarball.py
     |- toollib.py
 
+There are also some release utilities in :file:`nisext/testers.py`, with
+makefile targets for their use.  The relevant targets are::
+
+    make check-version-info
+    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.
+
+The second (``sdist-tests``) makes an sdist source distribution archive,
+installs it to a temporary directory, and runs the tests of that install.
+
 .. _release-checklist:
 
 Release checklist
 =================
 
-* Make sure all tests pass.
-
 * Review the open list of `issues <http://github.com/nipy/nibabel/issues>`_
 
-* Run :file:`build_release` from the :file:`tools` directory::
-
-    cd tools
-    ./build_release
-
 * Review and update the release notes.  Review and update the :file:`Changelog`
   file.  Get a partial list of contributors::
 
@@ -45,27 +51,59 @@ Release checklist
   Then manually go over the *git log* to make sure the release notes are
   as complete as possible and that every contributor was recognized.
 
-* Tag the release.
+* Make sure all tests pass::
+
+    nosetests --with-doctest nibabel
+
+* Make sure all tests pass from sdist::
+
+    make sdist-tests
+
+* First pass run :file:`build_release` from the :file:`tools` directory::
+
+    cd tools
+    ./build_release
+
+* The release should now be ready.
+
+* Edit :file:`nibabel/info.py` to set ``_version_extra`` to ``''``; commit
 
 * Once everything looks good, run :file:`release` from the
   :file:`tools` directory.
 
-* Announce to the mailing lists.
+* Tag the release with tag of form ``1.0.0``::
+
+    git tag -am 'First public release' 1.0.0
+
+* Branch to maintainance::
+
+    git co -b maint/1.0.0
 
-Releases
-========
+  Set ``_version_extra`` back to ``.dev`` and bump ``_version_micro`` by 1.
+  Commmit.  Push.
 
-After each release the master branch should be tagged
-with an annotated (or/and signed) tag, naming the intended
-next version, plus an 'upstream/' prefix and 'dev' suffix.
-For example 'upstream/1.0.0.dev' means "development start
-for upcoming version 1.0.0.
+* Start next development series::
 
-This tag is used in the Makefile rules to create development
-snapshot releases to create proper versions for those. The
-will name the last available annotated tag, the number of
-commits since that, and an abbrevated SHA1. See the docs of
-``git describe`` for more info.
+    git co main-master
+
+  then restore ``.dev`` to ``_version_extra``, and bump ``_version_minor`` by 1.
+
+* Make next development release tag
+
+    After each release the master branch should be tagged
+    with an annotated (or/and signed) tag, naming the intended
+    next version, plus an 'upstream/' prefix and 'dev' suffix.
+    For example 'upstream/1.0.0.dev' means "development start
+    for upcoming version 1.0.0.
+
+    This tag is used in the Makefile rules to create development
+    snapshot releases to create proper versions for those. The
+    will name the last available annotated tag, the number of
+    commits since that, and an abbrevated 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``.
+
+* Announce to the mailing lists.
 
-Please take a look at the Makefile rules ``devel-src``,
-``devel-dsc`` and ``orig-src``.

doc/source/index.rst

@@ -15,13 +15,13 @@ Documentation
 * :ref:`User Documentation <manual>` (manual)
 * :ref:`API Documentation <api>` (comprehensive reference)
 * :ref:`Developer Guidelines <chap_devguide>` (for those who want to contribute)
-* :ref:`Developer discussions <chap_devdiscuss>` (arcane discussions about code
-  design)
 * :ref:`Development Changelog <changelog>` (see what has changed)
 * :ref:`DICOM concepts <dicom>` (details about implementing DICOM reading)
 * :ref:`genindex` (access by keywords)
 * :ref:`search` (online and offline full-text search)
 
+See also the :ref:`Developer documentation page <devindex>` for development
+discussions, release procedure and more.
 
 Authors and Contributors
 ========================
@@ -50,7 +50,6 @@ Download and Installation
 Please find detailed :ref:`download and installation instructions
 <installation>` in the manual.
 
-
 Support
 =======
 
@@ -75,7 +74,6 @@ search* located in the sidebar of the NiBabel home page.
    :hidden:
 
    manual
-   devel/devguide
-   devel/devdiscuss
+   devel/index
    dicom/dicom
    api