Skip to content

Commit

Permalink
Developer docs: revise docs on versioning and creating a release
Browse files Browse the repository at this point in the history
  • Loading branch information
@willfurnass
willfurnass committed Mar 18, 2020
1 parent 275c1c4 commit d21992a
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 58 deletions.
21 changes: 7 additions & 14 deletions docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,6 @@
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
#sys.path.insert(0, os.path.abspath('../..'))
#sys.path.insert(0, os.path.abspath('../../mumot'))


# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
Expand All @@ -38,6 +28,7 @@
'sphinx.ext.doctest',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.extlinks',
'sphinx.ext.mathjax',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
Expand All @@ -59,17 +50,19 @@

# General information about the project.
project = 'MuMoT'
copyright = '2018, University of Sheffield'
copyright = '2020, University of Sheffield'
author = 'James A. R. Marshall, Andreagiovanni Reina, Thomas Bose'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
import mumot
#import mumot
from pkg_resources import get_distribution
release = get_distribution('mumot').version
# for example take major/minor
version = '.'.join(release.split('.')[:2])
version = '.'.join(release.split('.')[:3])

#binder_tag = f"v{version}" if release == version else "master"
#extlinks = {'binder': (f"https://mybinder.org/v2/gh/DiODeProject/MuMoT/{binder_tag}?filepath=%s.ipynb", "issue ")}

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
Expand Down
72 changes: 28 additions & 44 deletions docs/source/development.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ If you want to contribute a feature or fix a bug then:
Automated tests will then run against your branch (using Travis)
and your code will be reviewed by the core development team,
after which your changes will be merged into the main MuMoT repository *or*
you will be asked to make futher changes to your branch.
you will be asked to make further changes to your branch.

.. _testing:

Expand Down Expand Up @@ -299,11 +299,23 @@ In this project the use of branches and git tags is as follows:
- The ``master`` branch is the only long-lived *active* branch
- New features are developed by creating **feature branches** from the ``master`` branch;
these feature branches are then ultimately merged back into ``master`` via Pull Requests then deleted.
- Changes in patch, major and minor versions are defined **solely** by
creating an `annotated tag <https://git-scm.com/book/en/v2/Git-Basics-Tagging>`__
for a particular commit.
The name of this tag should be of the form ``v<major>.<minor>.<patch>``
i.e the version preceded by a ``v``.
**The version does not need to then be specified anywhere in the code
(other than in links to mybinder in the Sphinx docs)**:
whenever an installable release of MuMoT is created
the `setuptools_scm <https://pypi.org/project/setuptools-scm/>`__ package
will embed version information using the most recent tag on the current branch
plus extra information derived from the output of ``git describe``
if the most recent commit does not have an annotated tag associated with it.

To create a release:

#. Decide on the type of the next release (patch, major or minor),
which depends on the nature of the changes.
which depends on the nature of the changes.

#. (Related) determine the appropriate version number for this pending release.

Expand All @@ -313,29 +325,15 @@ To create a release:
are reassigned to a different Milestone.
Ensure all pull requests against ``master`` relating to the pending Milestone have been merged and all CI tests pass.

#. Create a pull request against ``master`` to bump the version in ``mumot/_version.py`` from e.g.
#. If necessary, create a pull request against ``master`` to change the version in links to mybinder e.g. in

.. code-block:: python
version_info = (0, 8, 0, 'dev')
__version__ = "{}.{}.{}-{}".format(*version_info)
to e.g.

.. code-block:: python
version_info = (0, 9, 0)
__version__ = "{}.{}.{}".format(*version_info)
.. code-block::
Package versions (``setup.py``) and
the version info in rendered Sphinx docs
are automatically set using this variable.
Ensure that the version number uses only digits,
to comply with PyPI naming restrictions.

Also, update the MuMoT version in all mybinder.org URLs in the README and Sphinx docs:
they should, in this case, contain ``v0.9.0`` (note the extra '``v``').
https://mybinder.org/v2/gh/DiODeProject/MuMoT/VERSION?filepath=docs%2FMuMoTuserManual.ipynb
ensure ``VERSION`` is ``master`` or
a particular current or future tagged version, preceded by a ``v`` e.g. ``v0.9.0``.

Also, check update citation info (including the DOI and contributors) for this pending release
in ``docs/source/about.rst``.

Expand All @@ -345,13 +343,14 @@ To create a release:
then you can see the first line of all commit comments since then with: ::

$ git checkout master
$ git log --pretty=oneline --abbrev-commit v0.9.0..HEAD
$ git log --pretty=oneline --abbrev-commit v0.8.0..HEAD

then: ::

$ git commit -a -m "Bumped version number to 0.9.0"
$ git commit -a -m "Preparing for release of version 0.9.0"
and create the Pull Request.
where 0.9.0 is the version of the new release.
Next, create the Pull Request.

#. Merge this Pull Request into ``master`` then create an *annotated tag*: ::

Expand All @@ -362,15 +361,17 @@ To create a release:
$ git push upstream --tags
$ git push

Here we assume that you've set up your local git repository with a remote called ``upstream`` that points at ``github.com/DiODeProject/MuMoT.git`` e.g. ::
Here we assume that you've set up your local git repository with a remote called ``upstream``
that points at ``github.com/DiODeProject/MuMoT.git`` e.g. ::

$ git remote -v
origin git@github.com:willfurnass/MuMoT.git (fetch)
origin git@github.com:willfurnass/MuMoT.git (push)
upstream git@github.com:DiODeProject/MuMoT.git (fetch)
upstream git@github.com:DiODeProject/MuMoT.git (push)

NB annotated tags are are often used within git repositories to identify the commits corresponding to particular releases.
NB annotated tags are are often used within git repositories to identify
the commit corresponding to a particular release.

#. The pushing of a tagged commit to ``github.com:DiODeProject/MuMoT.git`` causes Travis to:

Expand All @@ -380,7 +381,6 @@ To create a release:
* A binary 'wheel' package e.g. ``mumot-0.9.0-py3-none-any.whl``
* A source package e.g. ``mumot-0.9.0.tar.gz``


#. Upload these files to `PyPI <https://pypi.org/account/register/>`__
using environment variables stored as encrypted credentials in this Travis project.

Expand All @@ -393,22 +393,6 @@ To create a release:
* The release being referenceable/citable by DOI_.
* The release being discoverable via the University's Library Catalogue.

#. Finally, bump the version info on the ``master`` branch (not the ``release-...`` branch) by updating ``mumot/_version`` from e.g.

.. code-block:: python
version_info = (0, 8, 0, 'dev')
__version__ = "{}.{}.{}-{}".format(*version_info)
to e.g.

.. code-block:: python
version_info = (0, 9, 0, 'dev')
__version__ = "{}.{}.{}-{}".format(*version_info)
then merge this into ``master``.

..
https://github.com/scikit-learn/scikit-learn/wiki/How-to-make-a-release
Expand Down

0 comments on commit d21992a

Please sign in to comment.