Merge pull request #9193 from willingc/doc-release

Migrate release creation instructions from wiki to docs

docs/source/coredev/index.rst

@@ -0,0 +1,19 b''
+.. _core_developer_guide:
+
+==================================
+Developer's guide to core IPython
+==================================
+
+This guide documents the development of core IPython. Alternatively,
+developers of third party tools and libraries that use IPython should see the
+:doc:`../development/index`.
+
+Developers working on core IPython should also consult the
+`developer information <https://github.com/ipython/ipython/wiki/Dev:-Index>`_
+on the IPython GitHub wiki.
+
+.. toctree::
+   :maxdepth: 1
+
+   release_process
+   making_release

docs/source/coredev/making_release.rst

@@ -0,0 +1,56 b''
+.. making_release::
+
+Making an IPython release
+=========================
+
+1. Make sure the repository is clean of any file that could be problematic.
+   Remove all non-tracked files with:
+
+   .. code::
+
+       git clean -xfdi
+
+   This will ask for confirmation before removing all untracked files. Make
+   sure the ``dist/`` folder is clean to avoid any stale builds from
+   previous build attempts.
+
+2. Update version number and ``_version_extra`` content in
+   ``IPython/core/release.py``.
+
+   Make sure the version number matches pep440, in particular, `rc` and `beta`
+   are not separated by `.` or the `sdist` and `bdist` will appear as different
+   releases. For example, a valid version number for a release candidate (rc)
+   release is: ``1.3rc1``. Notice that there is no separator between the '3'
+   and the 'r'.
+
+
+3. Commit and tag the release with the current version number:
+
+   .. code::
+
+       git commit -am "release $VERSION"
+       git tag $VERSION
+
+
+4. Build the ``sdist`` and ``wheel``:
+
+   .. code::
+
+       python setup.py sdist --formats=zip,gztar
+       python2 setup.py bdist_wheel
+       python3 setup.py bdist_wheel
+
+
+5. Be sure to test the ``wheel`` and the ``sdist`` locally before uploading
+   them to PyPI. Make sure to use `twine <https://github.com/pypa/twine>`_ to
+   upload these archives over SSL.
+
+   .. code::
+
+       $ twine upload dist/*
+
+6. If all went well, change the ``_version_extra = ''`` in
+   ``IPython/core/release.py`` back to the ``.dev`` suffix, or
+   ``_version_extra='.dev'``.
+
+7. Push directly to master, remembering to push ``--tags`` too.
  No newline at end of file

docs/source/coredev/release_process.rst

@@ -0,0 +1,149 b''
+.. _release_process:
+
+=======================
+IPython release process
+=======================
+
+This document contains the process that is used to create an IPython release.
+
+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.
+
+1. 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
+    VERSION=1.1.0
+    TAG="rel-$VERSION"
+    BRANCH=master
+
+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.
+
+2. Create GitHub stats and finish release note
+----------------------------------------------
+
+.. note::
+
+    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:
+
+    - 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 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
+
+      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.
+
+To find duplicates and update `.mailmap`, use::
+
+    git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
+
+
+3. Run the `tools/build_release` script
+---------------------------------------
+
+Running `tools/build_release` 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.
+
+4. Create and push the new tag
+------------------------------
+
+Edit `IPython/core/release.py` to have the current version.
+
+Commit the changes to release.py and jsversion::
+
+    git commit -am "release $VERSION"
+    git push origin $BRANCH
+
+Create and push the tag::
+
+    git tag -am "release $VERSION" "$TAG"
+    git push origin --tags
+
+Update release.py back to `x.y-dev` or `x.y-maint`, and push::
+
+    git commit -am "back to development"
+    git push origin $BRANCH
+
+5. Get a fresh clone
+--------------------
+
+Get a fresh clone of the tag for building the release::
+
+    cd /tmp
+    git clone --depth 1 https://github.com/ipython/ipython.git -b "$TAG"
+
+6. Run the release script
+-------------------------
+
+Run the `release` script::
+
+    cd tools && ./release
+
+This makes the tarballs, zipfiles, and wheels.  It posts
+them to archive.ipython.org and registers the release with PyPI.
+
+This step requires having a current wheel, Python 3.4 and Python 2.7.
+
+7. Draft a short release announcement
+-------------------------------------
+
+The announcement should include:
+
+- release highlights
+- a link to the html version of the *What's new* section of the documentation
+- a link to upgrade or installation tips (if necessary)
+
+Post the announcement to the mailing list, and link from Twitter.
+
+8. Update milestones on GitHub
+------------------------------
+
+These steps will bring milestones up to date:
+
+- close the just released milestone
+- open a new milestone for the next release (x, y+1), if the milestone doesn't
+  exist already
+
+9. 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)
+
+10. Celebrate!
+--------------
+
+Celebrate the release and please thank the contributors for their work. Great
+job!
+

docs/source/development/index.rst

@@ -1,20 +1,14 b''
 .. _developer_guide:
 
-=========================
-IPython developer's guide
-=========================
+=====================================================
+Developer's guide for third party tools and libraries
+=====================================================
 
-This are two categories of developer focused documentation:
+.. important::
 
-1. Documentation for developers of *IPython itself*.
-2. Documentation for developers of third party tools and libraries
-   that use IPython.
-
-This part of our documentation only contains information in the second category.
-
-Developers interested in working on IPython itself should consult
-our `developer information <https://github.com/ipython/ipython/wiki/Dev:-Index>`_ 
-on the IPython GitHub wiki.
+    This guide contains information for developers of third party tools and
+    libraries that use IPython. Alternatively, documentation for core
+    **IPython** development can be found in the :doc:`../coredev/index`.
 
 .. toctree::
    :maxdepth: 1
@@ -26,52 +20,3 b' on the IPython GitHub wiki.'
    pycompat
    config
    inputhook_app
  No newline at end of file
-
-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``.
-

docs/source/index.rst

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