Migrate the wiki contents to release process doc

docs/source/coredev/old_release_doc.rst

@@ -0,0 +1,50
+.. old_release_doc::
+
+Making an IPython release [TODO:: Can this be replaced by the Release Process document???]
+==========================================================================================
+
+Make sure the repository is clean of any file that could be problematic.
+You can remove all non-tracked files with:
+
+.. code::
+
+    git clean -xfdi
+
+This would ask you for confirmation before removing all untracked files. Make
+sure the ``dist/`` folder is clean and avoid stale build from
+previous attempts.
+
+1. Update version number in ``IPython/core/release.py``.
+
+Make sure the version number match pep440, in particular, `rc` and `beta` are
+not separated by `.` or the `sdist` and `bdist` will appear as different
+releases.
+
+2. Commit and tag the release with the current version number:
+
+.. code::
+
+    git commit -am "release $VERSION"
+    git tag $VERSION
+
+
+3. You are now ready to build the ``sdist`` and ``wheel``:
+
+.. code::
+
+    python setup.py sdist --formats=zip,gztar
+    python2 setup.py bdist_wheel
+    python3 setup.py bdist_wheel
+
+
+4. You can now test the ``wheel`` and the ``sdist`` locally before uploading to PyPI.
+Make sure to use `twine <https://github.com/pypa/twine>`_ to upload the archives over SSL.
+
+.. code::
+
+    $ twine upload dist/*
+
+5. If all went well, change the ``IPython/core/release.py`` back adding the ``.dev`` suffix.
+
+6. Push directly on master, not forgetting to push ``--tags``.
+

docs/source/coredev/index.rst

@@ -16,52 +16,4 on the IPython GitHub wiki.
    :maxdepth: 1
 
    release_process
-
-Making an IPython release
-=========================
-
-Make sure the repository is clean of any file that could be problematic. 
-You can remove all non-tracked files with:
-
-.. code::
-
-    git clean -xfdi
-
-This would ask you for confirmation before removing all untracked files. Make
-sure the ``dist/`` folder is clean and avoid stale build from
-previous attempts.
-
-1. Update version number in ``IPython/core/release.py``.
-
-Make sure the version number match pep440, in particular, `rc` and `beta` are
-not separated by `.` or the `sdist` and `bdist` will appear as different
-releases.
-
-2. Commit and tag the release with the current version number:
-
-.. code::
-
-    git commit -am "release $VERSION"
-    git tag $VERSION
-
-
-3. You are now ready to build the ``sdist`` and ``wheel``:
-
-.. code::
-
-    python setup.py sdist --formats=zip,gztar
-    python2 setup.py bdist_wheel
-    python3 setup.py bdist_wheel
-
-
-4. You can now test the ``wheel`` and the ``sdist`` locally before uploading to PyPI.
-Make sure to use `twine <https://github.com/pypa/twine>`_ to upload the archives over SSL.
-
-.. code::
-
-    $ twine upload dist/*
-
-5. If all went well, change the ``IPython/core/release.py`` back adding the ``.dev`` suffix.
-
-6. Push directly on master, not forgetting to push ``--tags``.
-
+   old_release_doc

docs/source/coredev/release_process.rst

@@ -1,13 +1,20
-This document contains notes about the process that is used to release IPython.
-Our release process is currently not very formal and could be improved.
+.. _release_process:
 
-Most of the release process is automated by the `release` script in the `tools`
-directory of our main repository.  This document is just a handy reminder for
-the release manager.
+======================
+Releasing core IPython
+======================
 
-# 0. Environment variables
+This document contains the process that is used to create an IPython release.
 
-You can set some env variables to note previous release tag and current release milestone, version, and git tag:
+Conveniently, the `release` script in the `tools` directory of the `IPython`
+repository automates most of the release process. This document serves as a
+handy reminder and checklist for the release manager.
+
+#. Set Environment variables
+----------------------------
+
+Set environment variables to document previous release tag, current
+release milestone, current release version, and git tag:
 
     PREV_RELEASE=rel-1.0.0
     MILESTONE=1.1
@@ -15,37 +22,58 You can set some env variables to note previous release tag and current release
     TAG="rel-$VERSION"
     BRANCH=master
 
-These will be used later if you want to copy/paste, or you can just type the appropriate command when the time comes. These variables are not used by scripts (hence no `export`).
+These variables may be used later to copy/paste as answers to the script
+questions instead of typing the appropriate command when the time comes. These
+variables are not used by the scripts directly; therefore, there is no need to
+`export` the variables.
+
+#. Finish release notes
+-----------------------
+
+.. note::
 
-# 1. Finish release notes
+    Before generating the GitHub stats, verify that all closed issues and
+    pull requests `have appropriate milestones <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_.
+    `This search <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
+    should return no results before creating the GitHub stats.
 
-- If a major release:
+If a major release:
 
-  - merge any pull request notes into what's new:
+    - merge any pull request notes into what's new::
 
           python tools/update_whatsnew.py
 
-  - update `docs/source/whatsnew/development.rst`, to ensure it covers the major points.
-  - move the contents of `development.rst` to `versionX.rst`
-- generate summary of GitHub contributions, which can be done with:
+    - update `docs/source/whatsnew/development.rst`, to ensure it covers
+      the major release features
+    - move the contents of `development.rst` to `versionX.rst` where `X` is
+      the numerical release version
+    - generate summary of GitHub contributions, which can be done with::
 
-        python tools/github_stats.py --milestone $MILESTONE > stats.rst
+          python tools/github_stats.py --milestone $MILESTONE > stats.rst
 
-  which may need some manual cleanup. Add the cleaned up result and add it to `docs/source/whatsnew/github-stats-X.rst` (make a new file, or add it to the top, depending on whether it is a major release).
-  You can use:
+      which may need some manual cleanup of `stats.rst`. Add the cleaned
+      `stats.rst` results to `docs/source/whatsnew/github-stats-X.rst` where
+      `X` is the numerical release version. If creating a major release, make
+      a new `github-stats-X.rst` file; if creating a minor release, the
+      content from `stats.rst` may simply be added to the top of an existing
+      `github-stats-X.rst` file.
 
-        git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
+To find duplicates and update `.mailmap`, use:
 
-  to find duplicates and update `.mailmap`.
-  Before generating the GitHub stats, verify that all closed issues and pull requests [have appropriate milestones](https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones). [This search](https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue) should return no results.
+    git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
 
-# 2. Run the `tools/build_release` script
 
-This does all the file checking and building that the real release script will do.
-This will let you do test installations, check that the build procedure runs OK, etc.
-You may want to also do a test build of the docs.
+#. Run the `tools/build_release` script
+---------------------------------------
 
-# 3. Create and push the new tag
+This does all the file checking and building that the real release script will
+do. This makes test installations, checks that the build procedure runs OK,
+and tests other steps in the release process.
+
+We encourage creating a test build of the docs as well.
+
+#. Create and push the new tag
+------------------------------
 
 Edit `IPython/core/release.py` to have the current version.
 
@@ -64,36 +92,51 Update release.py back to `x.y-dev` or `x.y-maint`, and push:
     git commit -am "back to development"
     git push origin $BRANCH
 
-# 4. Get a fresh clone of the tag for building the release:
+#. Get a fresh clone
+--------------------
 
-    cd /tmp
-    git clone --depth 1 https://github.com/ipython/ipython.git -b "$TAG" 
+Get a fresh clone of the tag for building the release:
 
-# 5. Run the `release` script
+    cd /tmp
+    git clone --depth 1 https://github.com/ipython/ipython.git -b "$TAG"
 
-    cd tools && ./release
+#. Run the release script
+-------------------------
 
-This makes the tarballs, zipfiles, and wheels.  It posts them to archive.ipython.org and
-registers the release with PyPI.
+Run the `release` script::
 
-This will require that you have current wheel, Python 3.4 and Python 2.7.
+    cd tools && ./release
 
-# 7. Update the IPython website
+This makes the tarballs, zipfiles, and wheels.  It posts
+them to archive.ipython.org and registers the release with PyPI.
 
-- release announcement (news, announcements)
-- update current version and download links
-- (If major release) update links on the documentation page
+This step requires having a current wheel, Python 3.4 and Python 2.7.
 
-# 8. Drafting a short release announcement
+#. Draft a short release announcement
+-------------------------------------
 
 This should include i) highlights and ii) a link to the html version of
 the *What's new* section of the documentation.
 
-Post to mailing list, and link from Twitter.
+Post the announcement to the mailing list, and link from Twitter.
+
+#. Update milestones on GitHub
+------------------------------
+
+- close the just released milestone
+- open a new milestone for the next release (x, y+1), if the milestone doesn't
+  exist already
+
+#. Update the IPython website
+-----------------------------
+The IPython website should document the new release:
+
+- add release announcement (news, announcements)
+- update current version and download links
+- update links on the documentation page (especially if a major release)
 
-# 9. Update milestones on GitHub
+#. Celebrate!
+-------------
 
-- close the milestone you just released
-- open new milestone for (x, y+1), if it doesn't exist already
+Celebrate the release and thank the contributors for their work.
 
-# 10. Celebrate!

docs/source/development/index.rst

@@ -5,9 +5,9 Developer's guide for Third Party Tools and Libraries
 =====================================================
 
 .. important:
-    
+
     This guide contains information for developers of third party tools and
-    libraries that use IPython. Documentation for developers of core 
+    libraries that use IPython. Documentation for developers of co
     *IPython itself* can be found in the :doc:`coredev/index`.
 
 .. toctree::
@@ -24,7 +24,7 Developer's guide for Third Party Tools and Libraries
 Making an IPython release
 =========================
 
-Make sure the repository is clean of any file that could be problematic. 
+Make sure the repository is clean of any file that could be problematic.
 You can remove all non-tracked files with:
 
 .. code::

docs/source/index.rst

@@ -21,6 +21,7 Contents
    interactive/index
    config/index
    development/index
+   coredev/index
    api/index
    about/index