summaryrefslogtreecommitdiff
path: root/CONTRIBUTING.rst
diff options
context:
space:
mode:
authorTristan Van Berkom <tristan.vanberkom@codethink.co.uk>2019-02-17 21:30:11 +0900
committerTristan Van Berkom <tristan.vanberkom@codethink.co.uk>2019-02-18 17:41:57 +0900
commitee2296ab744f7298d7e756ee0b1a3b5be5e26387 (patch)
tree416cb33b341280975a2370822683b021daf97024 /CONTRIBUTING.rst
parent232906b13c946ab6d857d29df940cb8b21267be6 (diff)
downloadbuildstream-ee2296ab744f7298d7e756ee0b1a3b5be5e26387.tar.gz
CONTRIBUTING.rst: Documenting the release process
So that other people can also make releases.
Diffstat (limited to 'CONTRIBUTING.rst')
-rw-r--r--CONTRIBUTING.rst258
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>`_.