Add info about how to release a new version

doc/how-to-contribute.rst

@@ -56,3 +56,94 @@ favourite tool easily.
 .. _Sphinx: http://www.sphinx-doc.org/en/stable
 .. _PyLint: https://www.pylint.org
 .. _Codacy: https://www.codacy.com/app/tango-controls/pytango/dashboard
+
+Releasing a new version
+-----------------------
+
+From time to time a new version should be released.  The basic steps required are
+as follows:
+
+Pick a version number
+  * Semantic version numbering is used:  <major>.<minor>.<patch>
+  * The major and minor version fields (9.2) track the TANGO C++ core version.
+  * For small changes, increase the patch field (last number), for example:
+    9.2.4 -> 9.2.5
+
+Create an issue in Github
+  * This is to inform the community that a release is planned.
+  * Use a checklist similar to the one below:
+
+    | Task list:
+    | - [ ] Read steps in the how-to-contribute docs for making a release
+    | - [ ] Edit the changelog
+    | - [ ] Bump the version
+    | - [ ] Merge develop into stable
+    | - [ ] Make sure Travis is OK on stable branch
+    | - [ ] Make sure the documentation is updated (readthedocs)
+    | - [ ] Create a release tag on GitHub, from stable branch
+    | - [ ] Upload the new version to PyPI
+    | - [ ] Bump the version with "-dev" in the develop branch
+    | - [ ] Fill the release description on GitHub
+    | - [ ] Build conda packages
+    | - [ ] Advertise the release on the mailing list
+    | - [ ] Close this issue
+
+  * A check list is this form on github can be ticked off as the work progresses.
+
+Make a branch from `develop` to prepare the release
+  * Example branch name: ``prepare-v9.2.5``.
+  * Edit the changelog (in ``docs/revision.rst``).  Include *all* pull requests
+    since the previous release.
+  * Bump the versions in (in ``tango/release.py``).  E.g. ``version_info`` to (9, 2, 5)
+  * Create a pull request to get these changes reviewed before proceeding.
+
+Merging ``develop`` into ``stable``
+  * Wait until the preparation branch pull request has been merged.
+  * Merge ``stable`` into the latest ``develop``, and push to github.
+  * In general, the ``stable`` branch should point to the latest release.
+
+Make sure Travis is OK on ``stable`` branch
+  * All tests, on all versions of Python must be passing.
+    If not, bad luck - you'll have to fix it first, and go back a few steps...
+
+Make sure the documentation is updated
+  * Log in to https://readthedocs.org.
+  * Get account permissions for https://pytango.readthedocs.io from another contributor,
+    if necessary.
+  * Build the docs manually for new release, or does it happen automatically?
+  * Build docs for stable branch too?
+
+Create a release tag on GitHub
+  * On the Releases page, use "Draft a new release".
+  * Tag must match the format of previous tags, e.g. ``v9.2.5``.
+  * Target must be the ``stable`` branch.
+
+Upload the new version to PyPI
+  * Log in to https://pypi.org.
+  * Get account permissions for PyTango from another contributor, if necessary.
+  * Build update and upload?
+
+Bump the version with "-dev" in the develop branch
+  * Change all references to next version.  E.g. if releasing
+    v9.2.5, then update references to v9.2.6.
+  * This includes files like ``README.rst``, ``doc/howto.rst``, ``doc/start.rst``.
+  * In ``tango/release.py``, change ``version_info``, e.g. from ``(9, 2, 5)`` to
+    ``(9, 2, 6, 'dev', 0)``.
+
+Fill in the release description on GitHub
+  * Content must be the same as the details in the changelog.  List all the
+    pull requests since the previous version.
+
+Build conda packages
+  * Log in to https://anaconda.org.
+  * Get account permissions to ``tango-controls/pytango`` from another contributor,
+    if necessary.
+  * Trigger updated build?
+
+Advertise the release on the mailing list
+  * Post on the Python development list.
+  * Example of a previous post:  http://www.tango-controls.org/community/forum/c/development/python/pytango-921-release/
+
+Close off release issue
+  * All the items on the check list should be ticked off by now.
+  * Close the issue.