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/development_release.rst

@@ -0,0 +1,80 @@
+.. _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.
+
+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 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
+
+#.  Push tages on master forgetting to push ``--tags`` too.
+
+
+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,7 @@
-version_info = (5, 2, 0,'.dev')
-__version__ = '.'.join(map(str, version_info[0:3])) + ''.join(version_info[3:])
+from nbconvert._version_tools import create_valid_version
+
+version_info = (5, 2, 0)
+pre_info = ''
+dev_info = '.dev'
+__version__ = create_valid_version(version_info, pre_input=pre_info, dev_input=dev_info) 
+

nbconvert/_version_tools.py

@@ -0,0 +1,83 @@
+# import pep440 # cannot be imported as described below
+import re 
+
+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])
+
+    if is_canonical(out_version):
+        return out_version
+    else:
+        raise ValueError(pep440_err)
+
+# This has been ported directly from the pep440 package since it cannot be 
+# installed as part of a setuptools based install without using pyproject.toml
+
+posint = '(0|[1-9]\d*)'
+
+# 0!0.0.0rc0.post0.dev0
+
+tpl_string_re = ('^' # Start
+            '([1-9]\d*!)?'        # [N!]
+            '{posint}'            # N
+            '(\.{posint})*'        # (.N)*
+            '((a|b|rc){posint})?' # [{a|b|rc}N]
+            '(\.post{posint})?'  # [.postN]
+            '(\.dev{postdev})?'   # [.devN]
+            '$')
+string_re = tpl_string_re.format(posint=posint, postdev=posint)
+loose440re = re.compile(tpl_string_re.format(posint=posint, postdev=(posint+'?')))
+pep440re = re.compile(string_re)
+
+def is_canonical(version, loosedev=False):
+    """
+    Return whether or not the version string is canonical according to Pep 440
+    """
+    if loosedev:
+        return loose440re.match(version) is not None
+    return pep440re.match(version) is not None
+
+
+# this is the end of the direct port from pep440
+
+
+

setup.py

@@ -197,13 +197,20 @@ 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'],
 }
+s = [] 
+[s.extend(values) for values in extra_requirements.values()]
+extra_requirements['all'] = list(set(s))
+
+extras_require = setuptools_args['extras_require'] = {
+    **extra_requirements
+}
 
 if 'setuptools' in sys.modules:
     from setuptools.command.develop import develop