Add a core dev section to docs

docs/source/coredev/index.rst

@@ -0,0 +1,67 b''
+.. _core_developer_guide:
+
+==================================
+Developer's guide for core IPython
+==================================
+
+This guide documents the development of core *IPython itself*. Developers of
+third party tools and libraries that use IPython should see the 
+:doc:`development/index` at `Developer's guide for Third Party Tools and Libraries`.
+
+Developers working on IPython itself 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 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/coredev/release_process.rst

@@ -0,0 +1,99 b''
+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.
+
+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.
+
+# 0. Environment variables
+
+You can set some env variables to note previous release tag and current release milestone, version, and git tag:
+
+    PREV_RELEASE=rel-1.0.0
+    MILESTONE=1.1
+    VERSION=1.1.0
+    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`).
+
+# 1. Finish release notes
+
+- 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 points.
+  - move the contents of `development.rst` to `versionX.rst`
+- 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. 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:
+
+        git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
+
+  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.
+
+# 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.
+
+# 3. 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
+
+# 4. 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" 
+
+# 5. 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 will require that you have current wheel, Python 3.4 and Python 2.7.
+
+# 7. Update the IPython website
+
+- release announcement (news, announcements)
+- update current version and download links
+- (If major release) update links on the documentation page
+
+# 8. Drafting 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.
+
+# 9. Update milestones on GitHub
+
+- close the milestone you just released
+- open new milestone for (x, y+1), if it doesn't exist already
+
+# 10. Celebrate!

docs/source/development/index.rst

@@ -1,20 +1,14 b''
 .. _developer_guide:
 
-=========================
-IPython developer's guide
-=========================
-
-This are two categories of developer focused documentation:
-
-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.
+=====================================================
+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 
+    *IPython itself* can be found in the :doc:`coredev/index`.
 
 .. toctree::
    :maxdepth: 1