CONTRIBUTING.rst: Documenting the release process

So that other people can also make releases.

1 files changed, 258 insertions, 0 deletions

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index b993b08b6..6a3fbf05f 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1234,6 +1234,8 @@ This will give you a ``doc/build/html`` directory with the html docs which
 you can view in your browser locally to test.
 
 
+.. _contributing_session_html:
+
 Regenerating session html
 '''''''''''''''''''''''''
 The documentation build will build the session files if they are missing,
@@ -1252,6 +1254,8 @@ To force rebuild session html while building the doc, simply run `tox` with the
   env BST_FORCE_SESSION_REBUILD=1 tox -e docs
 
 
+.. _contributing_man_pages:
+
 Man pages
 ~~~~~~~~~
 Unfortunately it is quite difficult to integrate the man pages build
@@ -1779,3 +1783,257 @@ changing the ``.in`` file, run the following to update the matching ``.txt``
 file::
 
    make -C requirements
+
+
+Making releases
+---------------
+This is a checklist of activities which must be observed when creating
+BuildStream releases, it is important to keep this section up to date
+whenever the release process changes.
+
+
+Requirements
+~~~~~~~~~~~~
+There are a couple of requirements and accounts required in order
+to publish a release.
+
+* Ability to send email to ``buildstream-list@gnome.org`` and
+  to ``gnome-announce-list@gnome.org``.
+
+* Shell account at ``master.gnome.org``.
+
+* Access to the `BuildStream project on PyPI <https://pypi.org/project/BuildStream/>`_
+
+* An email client which still knows how to send emails in plain text.
+
+
+Pre-release changes
+~~~~~~~~~~~~~~~~~~~
+Before actually rolling the release, here is a list of changes which
+might need to be done in preparation of the release.
+
+* Ensure that the man pages are up to date
+
+  The man pages are committed to the repository because we are
+  currently unable to integrate this generation into the setuptools
+  build phase, as outlined in issue #8.
+
+  If any of the user facing CLI has changed, or if any of the
+  related docstrings have changed, then you should
+  :ref:`regenerate the man pages <contributing_man_pages>` and
+  add/commit the results before wrapping a release.
+
+* Ensure the documentation session HTML is up to date
+
+  The session HTML files are committed to the repository for multiple
+  reasons, one of them being that the documentation must be buildable
+  from within a release build environment so that downstream distribution
+  packagers can easily create the docs package.
+
+  This is currently only needed for the first stable release
+  in a stable line of releases, after this point the API is frozen
+  and will not change for the remainder of the stable release lifetime,
+  so nothing interesting will have changed in these session files.
+
+  If regeneration is needed, follow :ref:`the instructions above <contributing_session_html>`.
+
+* Ensure the NEWS entry is up to date and ready
+
+  For a stable release where features have not been added, we
+  should at least add some entries about the issues which have
+  been fixed since the last stable release.
+
+  For development releases, it is worthwhile going over the
+  existing entries and ensuring all the major feature additions
+  are mentioned and there are no redundancies.
+
+* Push pre-release changes
+
+  Now that any final pre-release changes to generated files or NEWS have
+  been made, push these directly to the upstream repository.
+
+  Do not sit around waiting for CI or approval, these superficial changes
+  do not affect CI and you are intended to push these changes directly
+  to the upstream repository.
+
+
+Release process
+~~~~~~~~~~~~~~~
+
+* Ensure that the latest commit is passing in CI
+
+  Of course, we do not release software which does not pass it's own
+  tests.
+
+* Get the list of contributors
+
+  The list of contributors for a given list is a list of
+  any contributors who have landed any patches since the
+  last release.
+
+  An easy way to get this list is to ask git to summarize
+  the authors of commits since the *last release tag*. For
+  example, if we are about to create the ``1.1.1`` release, then
+  we need to observe all of the commits since the ``1.1.0``
+  release:
+
+  .. code:: shell
+
+     git shortlog -s 1.1.0...@
+
+  At times, the same contributor might make contributions from different
+  machines which they have setup their author names differently, you
+  can see that some of the authors are actually duplicates, then
+  remove the duplicates.
+
+* Start composing the release announcement email
+
+  The first thing to do when composing the release email is to
+  ensure your mail client has disabled any HTML formatting and will
+  safely use plain text only.
+
+  Try to make the release announcement consistent with other release
+  announcements as much as possible, an example of the email
+  can be `found here <https://mail.gnome.org/archives/buildstream-list/2019-February/msg00039.html>`_.
+
+  The recipients of the email are ``buildstream-list@gnome.org`` and
+  ``gnome-announce-list@gnome.org`` and the title of the email should
+  be of the form: ``BuildStream 1.1.1 released``, without any exclamation point.
+
+  The format of the email is essentially::
+
+    Hi all,
+
+    This is the personalized message written to you about this
+    release.
+
+    If this is an unstable release, this should include a warning
+    to this effect and an invitation to users to please help us
+    test this release.
+
+    This is also a good place to highlight specific bug fixes which
+    users may have been waiting for, or highlight a new feature we
+    want users to try out.
+
+
+    What is BuildStream ?
+    =====================
+    This is a concise blurb which describes BuildStream in a couple of
+    sentences, and is taken from the the README.rst.
+
+    The easiest thing is to just copy this over from the last release email.
+
+
+    =================
+    buildstream 1.1.1
+    =================
+    This section is directly copy pasted from the top of the NEWS file
+
+
+    Contributors
+    ============
+     - This is Where
+     - You Put
+     - The Contributor
+     - Names Which
+     - You Extracted
+     - Using git shortlog -s
+
+
+    Where can I get it ?
+    ====================
+    https://download.gnome.org/sources/BuildStream/1.1/
+
+    For more information on the BuildStream project, visit our home page
+    at https://buildstream.build/
+
+* Publish the release tag
+
+  Now that any pre-release changes are upstream, create and push the
+  signed release tag like so:
+
+  .. code:: shell
+
+     git tag -s 1.1.1
+     git push origin 1.1.1
+
+* Upload the release tarball
+
+  First get yourself into a clean repository state, ensure that you
+  don't have any unfinished work or precious, uncommitted files lying
+  around in your checkout and then run:
+
+  .. code:: shell
+
+     git clean -xdff
+
+  Create the tarball with the following command:
+
+  .. code:: shell
+
+     python3 setup.py sdist
+
+  And upload the resulting tarball to the master GNOME server:
+
+  .. code:: shell
+
+     scp dist/BuildStream-1.1.1.tar.gz <user>@master.gnome.org:
+
+  And finally login to your account at ``master.gnome.org`` and run
+  the install scripts to publish the tarball and update the mirrors:
+
+  .. code:: shell
+
+     ftpadmin install BuildStream-1.1.1.tar.gz
+
+* Send the release email
+
+  Now that the release tag is up and the tarball is published,
+  you can send the release email.
+
+
+Post-release activities
+~~~~~~~~~~~~~~~~~~~~~~~
+Once the release has been published, there are some activities
+which need to be done to ensure everything is up to date.
+
+* If this is a stable release, then the tarball should also be
+  uploaded to PyPI.
+
+  Make sure you have ``twine`` installed and upload the tarball
+  like so:
+
+  .. code:: shell
+
+     pip3 install --user twine
+     twine upload -r pypi dist/BuildStream-1.0.1.tar.gz
+
+* Update the topic line in the #buildstream IRC channel if needed
+
+  The IRC channel usually advertizes the latest stable release
+  in the topic line, now is the right time to update it.
+
+* Update the website repository
+
+  The website wants to link to release announcements, but this
+  cannot be automated because we cannot guess what the link to
+  the release email will be in the mailing list archive.
+
+  Find the URL to the announcement you just published
+  `in the mailing list archives <https://mail.gnome.org/archives/buildstream-list/>`_,
+  and use that URL to update the ``anouncements.json`` file in the website
+  repository.
+
+  Commit and push this change to the the ``anouncements.json`` file to
+  the upstream website repository, and gitlab will take care of automatically
+  updating the website accordingly.
+
+* Regenerate BuildStream documentation
+
+  In order to update the badges we use in various documentation
+  which reflects what is the latest stable releases and the latest
+  development snapshots, we simply need to ensure a pipeline runs
+  for the master branch in the BuildStream repository.
+
+  You can do this by using the "Run Pipeline" feature on the
+  `pipelines page in the gitlab UI <https://gitlab.com/BuildStream/buildstream/pipelines>`_.