Better releases

CONTRIBUTING.md

@@ -3,3 +3,18 @@
 We follow the
 [Jupyter Contribution Workflow](https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html)
 and the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/master/CONTRIBUTING.md).
+
+# Testing
+
+In order to test all the features of nbconvert you need to have `pandoc` and
+`TexLive` installed. 
+
+In your environment `pip install nbconvert[all]` will be needed to be able to
+run all of the tests and to test all of the features. 
+
+If you only want to run some of the tests run `pip install nbconvert[test]`.
+
+# Releasing
+
+If you are going to release a version of `nbconvert` you should also be capable
+of testing it. Please follow the instructions in [Testing](#testing).

docs/source/changelog.rst

@@ -1,3 +1,5 @@
+.. _changelog:
+
 Changes in nbconvert
 ====================
 

docs/source/development_release.rst

@@ -0,0 +1,81 @@
+.. _nbconvert_release:
+
+Making an ``nbconvert`` release
+===============================
+
+This document guides a contributor through creating a release of ``nbconvert``.
+
+
+Assign all merged PRs to milestones
+-----------------------------------
+
+Go to GitHub and assign all PRs that have been merged to milestones.  This will
+be helpful when you update the changelog. If you go to this `GitHub page <Github
+no milestones_>`_ you will find all the PRs that currently have no milestones.
+
+.. _GitHub no milestones: https://github.com/jupyter/nbconvert/pulls?utf8=%E2%9C%93&q=is%3Amerged%20is%3Apr%20no%3Amilestone%20
+
+Check installed tools
+---------------------
+
+Review ``CONTRIBUTING.md``, particularly the testing and release sections.
+
+Clean the repository
+--------------------
+
+You can remove all non-tracked files with:
+
+.. code:: bash
+
+    git clean -xfdi
+
+This would ask you for confirmation before removing all untracked files. 
+
+Make sure the ``dist/`` folder is clean and avoid stale builds from
+previous attempts.
+
+Create the release
+------------------
+
+#.  Update the :doc:`changelog <changelog>` to account for all the PRs assigned to this milestone.
+
+#.  Update version number in ``notebook/_version.py``.
+
+#.  Commit and tag the release with the current version number:
+
+    .. code:: bash
+
+        git commit -am "release $VERSION"
+        git tag $VERSION
+
+#.  You are now ready to build the ``sdist`` and ``wheel``:
+
+    .. code:: bash
+
+        python setup.py sdist
+        python setup.py bdist_wheel
+
+#.  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:: bash
+
+        twine upload dist/*
+
+Release the new version
+-----------------------
+
+Push directly on master, including --tags separately
+
+    .. code:: bash
+
+        git push upstream 
+        git push upstream --tags
+
+
+Return to development state
+---------------------------
+
+If all went well, change the ``notebook/_version.py`` back adding the
+    ``.dev`` suffix.

docs/source/index.rst

@@ -54,6 +54,7 @@ batch of notebook files to another format.
 
    architecture
    api/index
+   development_release
 
 .. toctree::
    :maxdepth: 2

nbconvert/_version.py

@@ -1,2 +1,63 @@
-version_info = (5, 2, 0,'.dev')
-__version__ = '.'.join(map(str, version_info[0:3])) + ''.join(version_info[3:])
+version_info = (5, 2, 0)
+pre_info = ''
+dev_info = '.dev'
+
+def create_valid_version(release_info, epoch=None, pre_input='', dev_input=''):
+    '''
+    Creates a pep440 valid version of version number given a tuple integers 
+    and optional epoch, prerelease and developmental info. 
+
+    Parameters
+    ----------
+    release_info : Tuple(Int)
+    epoch : Int, default None
+    pre_input : Str, default ''
+    dev_input : Str, default ''
+    '''
+
+    pep440_err = "The version number is not a pep 440 compliant version number"
+
+
+    if epoch is not None:
+        epoch_seg = str(epoch) + '!'
+    else:
+        epoch_seg = ''
+
+    release_seg = '.'.join(map(str, release_info))
+
+    _magic_pre =  ['a','b','rc']
+    if pre_input!='' and not any([pre_input.startswith(prefix) for prefix in _magic_pre]):
+        raise ValueError(pep440_err + "\n please fix your prerelease segment.")
+    else:
+        pre_seg = pre_input
+
+    if dev_input=='':
+        dev_seg = dev_input
+    elif not dev_input.startswith('.') and dev_input.startswith('dev'):
+        dev_seg = ''.join(['.', dev_input])
+    elif dev_input.startswith('.dev'):
+        dev_seg = dev_input
+    elif dev_input!='':
+        raise ValueError(pep440_err + "\n please fix your development segment.")
+
+    if dev_input!='' and not any([dev_seg.endswith(str(n)) for n in range(10)]):
+        dev_seg = ''.join([dev_seg,'0'])
+
+    out_version = ''.join([epoch_seg, release_seg, pre_seg, dev_seg])
+
+
+    import re
+    def is_canonical(version):
+        return re.match(r'^([1-9]\d*!)?(0|[1-9]\d*)'
+                        r'(\.(0|[1-9]\d*))*((a|b|rc)(0|[1-9]\d*))?'
+                        r'(\.post(0|[1-9]\d*))?(\.dev(0|[1-9]\d*))?$', 
+                        version
+                        ) is not None
+
+    if is_canonical(out_version):
+        return out_version
+    else:
+        raise ValueError(pep440_err)
+
+
+__version__ = create_valid_version(version_info, pre_input=pre_info, dev_input=dev_info) 

setup.py

@@ -197,13 +197,15 @@ def run(self):
     'testpath', 
 ]
 
-extras_require = setuptools_args['extras_require'] = {
+extra_requirements = {
     # FIXME: tests still require nose for some utility calls,
     # but we are running with pytest
-    'test': ['pytest', 'pytest-cov', 'nose', 'ipykernel', 'jupyter_client'],
+    'test': ['pytest', 'pytest-cov', 'nose', 'ipykernel', 'jupyter_client>=4.2'],
     'serve': ['tornado>=4.0'],
     'execute': ['jupyter_client>=4.2'],
 }
+extra_requirements['all'] = sum(extra_requirements.values(), [])
+setuptools_args['extras_require'] = extra_requirements
 
 if 'setuptools' in sys.modules:
     from setuptools.command.develop import develop