Add release instructions for IPython.

Mostly adapt from notebooks one.

IPython/core/release.py

@@ -22,7 +22,7 b" name = 'ipython'"
 _version_major = 4
 _version_minor = 1
 _version_patch = 0
-_version_extra = 'dev'
+_version_extra = '.dev'
 # _version_extra = 'rc1'
 # _version_extra = ''  # Uncomment this for full releases
 
@@ -34,7 +34,7 b' _ver = [_version_major, _version_minor, _version_patch]'
 
 __version__ = '.'.join(map(str, _ver))
 if _version_extra:
-    __version__ = __version__ + '-' + _version_extra
+    __version__ = __version__  + _version_extra
 
 version = __version__  # backwards compatibility name
 version_info = (_version_major, _version_minor, _version_patch, _version_extra)

docs/source/development/index.rst

@@ -26,3 +26,51 b' on the IPython GitHub wiki.'
    pycompat
    config
    inputhook_app
+
+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
+    $ python 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``.
+

setup.py

@@ -23,6 +23,7 b' requires utilities which are not available under Windows."""'
 from __future__ import print_function
 
 import sys
+import re
 
 # This check is also made in IPython/__init__, don't forget to update both when
 # changing Python version requirements.
@@ -42,7 +43,6 b' PY3 = (sys.version_info[0] >= 3)'
 
 # Stdlib imports
 import os
-import shutil
 
 from glob import glob
 
@@ -291,7 +291,14 b' else:'
 
 setup_args.update(setuptools_extra_args)
 
+
+# loose as `.dev` is suppose to be invalid
+loose_pep440re = re.compile('^(\d+)\.(\d+)\.(\d+((a|b|rc)\d+)?)(\.post\d+)?(\.dev\d*)?$')
+
 def main():
+    import IPython.core.release as r
+    if not loose_pep440re.match(r.version):
+        raise ValueError("Version number '%s' is not valid (should match [N!]N(.N)*[{a|b|rc}N][.postN][.devN])" % r.version)
     setup(**setup_args)
 
 if __name__ == '__main__':