| ... |
... |
@@ -1234,6 +1234,8 @@ This will give you a ``doc/build/html`` directory with the html docs which |
|
1234
|
1234
|
you can view in your browser locally to test.
|
|
1235
|
1235
|
|
|
1236
|
1236
|
|
|
|
1237
|
+.. _contributing_session_html:
|
|
|
1238
|
+
|
|
1237
|
1239
|
Regenerating session html
|
|
1238
|
1240
|
'''''''''''''''''''''''''
|
|
1239
|
1241
|
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 |
|
1252
|
1254
|
env BST_FORCE_SESSION_REBUILD=1 tox -e docs
|
|
1253
|
1255
|
|
|
1254
|
1256
|
|
|
|
1257
|
+.. _contributing_man_pages:
|
|
|
1258
|
+
|
|
1255
|
1259
|
Man pages
|
|
1256
|
1260
|
~~~~~~~~~
|
|
1257
|
1261
|
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`` |
|
1779
|
1783
|
file::
|
|
1780
|
1784
|
|
|
1781
|
1785
|
make -C requirements
|
|
|
1786
|
+
|
|
|
1787
|
+
|
|
|
1788
|
+Making releases
|
|
|
1789
|
+---------------
|
|
|
1790
|
+This is a checklist of activities which must be observed when creating
|
|
|
1791
|
+BuildStream releases, it is important to keep this section up to date
|
|
|
1792
|
+whenever the release process changes.
|
|
|
1793
|
+
|
|
|
1794
|
+
|
|
|
1795
|
+Requirements
|
|
|
1796
|
+~~~~~~~~~~~~
|
|
|
1797
|
+There are a couple of requirements and accounts required in order
|
|
|
1798
|
+to publish a release.
|
|
|
1799
|
+
|
|
|
1800
|
+* Ability to send email to ``buildstream-list gnome org`` and
|
|
|
1801
|
+ to ``gnome-announce-list gnome org``.
|
|
|
1802
|
+
|
|
|
1803
|
+* Shell account at ``master.gnome.org``.
|
|
|
1804
|
+
|
|
|
1805
|
+* Access to the `BuildStream project on PyPI <https://pypi.org/project/BuildStream/>`_
|
|
|
1806
|
+
|
|
|
1807
|
+* An email client which still knows how to send emails in plain text.
|
|
|
1808
|
+
|
|
|
1809
|
+
|
|
|
1810
|
+Pre-release changes
|
|
|
1811
|
+~~~~~~~~~~~~~~~~~~~
|
|
|
1812
|
+Before actually rolling the release, here is a list of changes which
|
|
|
1813
|
+might need to be done in preparation of the release.
|
|
|
1814
|
+
|
|
|
1815
|
+* Ensure that the man pages are up to date
|
|
|
1816
|
+
|
|
|
1817
|
+ The man pages are committed to the repository because we are
|
|
|
1818
|
+ currently unable to integrate this generation into the setuptools
|
|
|
1819
|
+ build phase, as outlined in issue #8.
|
|
|
1820
|
+
|
|
|
1821
|
+ If any of the user facing CLI has changed, or if any of the
|
|
|
1822
|
+ related docstrings have changed, then you should
|
|
|
1823
|
+ :ref:`regenerate the man pages <contributing_man_pages>` and
|
|
|
1824
|
+ add/commit the results before wrapping a release.
|
|
|
1825
|
+
|
|
|
1826
|
+* Ensure the documentation session HTML is up to date
|
|
|
1827
|
+
|
|
|
1828
|
+ The session HTML files are committed to the repository for multiple
|
|
|
1829
|
+ reasons, one of them being that the documentation must be buildable
|
|
|
1830
|
+ from within a release build environment so that downstream distribution
|
|
|
1831
|
+ packagers can easily create the docs package.
|
|
|
1832
|
+
|
|
|
1833
|
+ This is currently only needed for the first stable release
|
|
|
1834
|
+ in a stable line of releases, after this point the API is frozen
|
|
|
1835
|
+ and will not change for the remainder of the stable release lifetime,
|
|
|
1836
|
+ so nothing interesting will have changed in these session files.
|
|
|
1837
|
+
|
|
|
1838
|
+ If regeneration is needed, follow :ref:`the instructions above <contributing_session_html>`.
|
|
|
1839
|
+
|
|
|
1840
|
+* Ensure the NEWS entry is up to date and ready
|
|
|
1841
|
+
|
|
|
1842
|
+ For a stable release where features have not been added, we
|
|
|
1843
|
+ should at least add some entries about the issues which have
|
|
|
1844
|
+ been fixed since the last stable release.
|
|
|
1845
|
+
|
|
|
1846
|
+ For development releases, it is worthwhile going over the
|
|
|
1847
|
+ existing entries and ensuring all the major feature additions
|
|
|
1848
|
+ are mentioned and there are no redundancies.
|
|
|
1849
|
+
|
|
|
1850
|
+* Push pre-release changes
|
|
|
1851
|
+
|
|
|
1852
|
+ Now that any final pre-release changes to generated files or NEWS have
|
|
|
1853
|
+ been made, push these directly to the upstream repository.
|
|
|
1854
|
+
|
|
|
1855
|
+ Do not sit around waiting for CI or approval, these superficial changes
|
|
|
1856
|
+ do not affect CI and you are intended to push these changes directly
|
|
|
1857
|
+ to the upstream repository.
|
|
|
1858
|
+
|
|
|
1859
|
+
|
|
|
1860
|
+Release process
|
|
|
1861
|
+~~~~~~~~~~~~~~~
|
|
|
1862
|
+
|
|
|
1863
|
+* Ensure that the latest commit is passing in CI
|
|
|
1864
|
+
|
|
|
1865
|
+ Of course, we do not release software which does not pass it's own
|
|
|
1866
|
+ tests.
|
|
|
1867
|
+
|
|
|
1868
|
+* Get the list of contributors
|
|
|
1869
|
+
|
|
|
1870
|
+ The list of contributors for a given list is a list of
|
|
|
1871
|
+ any contributors who have landed any patches since the
|
|
|
1872
|
+ last release.
|
|
|
1873
|
+
|
|
|
1874
|
+ An easy way to get this list is to ask git to summarize
|
|
|
1875
|
+ the authors of commits since the *last release tag*. For
|
|
|
1876
|
+ example, if we are about to create the ``1.1.1`` release, then
|
|
|
1877
|
+ we need to observe all of the commits since the ``1.1.0``
|
|
|
1878
|
+ release:
|
|
|
1879
|
+
|
|
|
1880
|
+ .. code:: shell
|
|
|
1881
|
+
|
|
|
1882
|
+ git shortlog -s 1.1.0...@
|
|
|
1883
|
+
|
|
|
1884
|
+ At times, the same contributor might make contributions from different
|
|
|
1885
|
+ machines which they have setup their author names differently, you
|
|
|
1886
|
+ can see that some of the authors are actually duplicates, then
|
|
|
1887
|
+ remove the duplicates.
|
|
|
1888
|
+
|
|
|
1889
|
+* Start composing the release announcement email
|
|
|
1890
|
+
|
|
|
1891
|
+ The first thing to do when composing the release email is to
|
|
|
1892
|
+ ensure your mail client has disabled any HTML formatting and will
|
|
|
1893
|
+ safely use plain text only.
|
|
|
1894
|
+
|
|
|
1895
|
+ Try to make the release announcement consistent with other release
|
|
|
1896
|
+ announcements as much as possible, an example of the email
|
|
|
1897
|
+ can be `found here <https://mail.gnome.org/archives/buildstream-list/2019-February/msg00039.html>`_.
|
|
|
1898
|
+
|
|
|
1899
|
+ The recipients of the email are ``buildstream-list gnome org`` and
|
|
|
1900
|
+ ``gnome-announce-list gnome org`` and the title of the email should
|
|
|
1901
|
+ be of the form: ``BuildStream 1.1.1 released``, without any exclamation point.
|
|
|
1902
|
+
|
|
|
1903
|
+ The format of the email is essentially::
|
|
|
1904
|
+
|
|
|
1905
|
+ Hi all,
|
|
|
1906
|
+
|
|
|
1907
|
+ This is the personalized message written to you about this
|
|
|
1908
|
+ release.
|
|
|
1909
|
+
|
|
|
1910
|
+ If this is an unstable release, this should include a warning
|
|
|
1911
|
+ to this effect and an invitation to users to please help us
|
|
|
1912
|
+ test this release.
|
|
|
1913
|
+
|
|
|
1914
|
+ This is also a good place to highlight specific bug fixes which
|
|
|
1915
|
+ users may have been waiting for, or highlight a new feature we
|
|
|
1916
|
+ want users to try out.
|
|
|
1917
|
+
|
|
|
1918
|
+
|
|
|
1919
|
+ What is BuildStream ?
|
|
|
1920
|
+ =====================
|
|
|
1921
|
+ This is a concise blurb which describes BuildStream in a couple of
|
|
|
1922
|
+ sentences, and is taken from the the README.rst.
|
|
|
1923
|
+
|
|
|
1924
|
+ The easiest thing is to just copy this over from the last release email.
|
|
|
1925
|
+
|
|
|
1926
|
+
|
|
|
1927
|
+ =================
|
|
|
1928
|
+ buildstream 1.1.1
|
|
|
1929
|
+ =================
|
|
|
1930
|
+ This section is directly copy pasted from the top of the NEWS file
|
|
|
1931
|
+
|
|
|
1932
|
+
|
|
|
1933
|
+ Contributors
|
|
|
1934
|
+ ============
|
|
|
1935
|
+ - This is Where
|
|
|
1936
|
+ - You Put
|
|
|
1937
|
+ - The Contributor
|
|
|
1938
|
+ - Names Which
|
|
|
1939
|
+ - You Extracted
|
|
|
1940
|
+ - Using git shortlog -s
|
|
|
1941
|
+
|
|
|
1942
|
+
|
|
|
1943
|
+ Where can I get it ?
|
|
|
1944
|
+ ====================
|
|
|
1945
|
+ https://download.gnome.org/sources/BuildStream/1.1/
|
|
|
1946
|
+
|
|
|
1947
|
+ For more information on the BuildStream project, visit our home page
|
|
|
1948
|
+ at https://buildstream.build/
|
|
|
1949
|
+
|
|
|
1950
|
+* Publish the release tag
|
|
|
1951
|
+
|
|
|
1952
|
+ Now that any pre-release changes are upstream, create and push the
|
|
|
1953
|
+ signed release tag like so:
|
|
|
1954
|
+
|
|
|
1955
|
+ .. code:: shell
|
|
|
1956
|
+
|
|
|
1957
|
+ git tag -s 1.1.1
|
|
|
1958
|
+ git push origin 1.1.1
|
|
|
1959
|
+
|
|
|
1960
|
+* Upload the release tarball
|
|
|
1961
|
+
|
|
|
1962
|
+ First get yourself into a clean repository state, ensure that you
|
|
|
1963
|
+ don't have any unfinished work or precious, uncommitted files lying
|
|
|
1964
|
+ around in your checkout and then run:
|
|
|
1965
|
+
|
|
|
1966
|
+ .. code:: shell
|
|
|
1967
|
+
|
|
|
1968
|
+ git clean -xdff
|
|
|
1969
|
+
|
|
|
1970
|
+ Create the tarball with the following command:
|
|
|
1971
|
+
|
|
|
1972
|
+ .. code:: shell
|
|
|
1973
|
+
|
|
|
1974
|
+ python3 setup.py sdist
|
|
|
1975
|
+
|
|
|
1976
|
+ And upload the resulting tarball to the master GNOME server:
|
|
|
1977
|
+
|
|
|
1978
|
+ .. code:: shell
|
|
|
1979
|
+
|
|
|
1980
|
+ scp dist/BuildStream-1.1.1.tar.gz <user>@master.gnome.org:
|
|
|
1981
|
+
|
|
|
1982
|
+ And finally login to your account at ``master.gnome.org`` and run
|
|
|
1983
|
+ the install scripts to publish the tarball and update the mirrors:
|
|
|
1984
|
+
|
|
|
1985
|
+ .. code:: shell
|
|
|
1986
|
+
|
|
|
1987
|
+ ftpadmin install BuildStream-1.1.1.tar.gz
|
|
|
1988
|
+
|
|
|
1989
|
+* Send the release email
|
|
|
1990
|
+
|
|
|
1991
|
+ Now that the release tag is up and the tarball is published,
|
|
|
1992
|
+ you can send the release email.
|
|
|
1993
|
+
|
|
|
1994
|
+
|
|
|
1995
|
+Post-release activities
|
|
|
1996
|
+~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
1997
|
+Once the release has been published, there are some activities
|
|
|
1998
|
+which need to be done to ensure everything is up to date.
|
|
|
1999
|
+
|
|
|
2000
|
+* If this is a stable release, then the tarball should also be
|
|
|
2001
|
+ uploaded to PyPI.
|
|
|
2002
|
+
|
|
|
2003
|
+ Make sure you have ``twine`` installed and upload the tarball
|
|
|
2004
|
+ like so:
|
|
|
2005
|
+
|
|
|
2006
|
+ .. code:: shell
|
|
|
2007
|
+
|
|
|
2008
|
+ pip3 install --user twine
|
|
|
2009
|
+ twine upload -r pypi dist/BuildStream-1.0.1.tar.gz
|
|
|
2010
|
+
|
|
|
2011
|
+* Update the topic line in the #buildstream IRC channel if needed
|
|
|
2012
|
+
|
|
|
2013
|
+ The IRC channel usually advertizes the latest stable release
|
|
|
2014
|
+ in the topic line, now is the right time to update it.
|
|
|
2015
|
+
|
|
|
2016
|
+* Update the website repository
|
|
|
2017
|
+
|
|
|
2018
|
+ The website wants to link to release announcements, but this
|
|
|
2019
|
+ cannot be automated because we cannot guess what the link to
|
|
|
2020
|
+ the release email will be in the mailing list archive.
|
|
|
2021
|
+
|
|
|
2022
|
+ Find the URL to the announcement you just published
|
|
|
2023
|
+ `in the mailing list archives <https://mail.gnome.org/archives/buildstream-list/>`_,
|
|
|
2024
|
+ and use that URL to update the ``anouncements.json`` file in the website
|
|
|
2025
|
+ repository.
|
|
|
2026
|
+
|
|
|
2027
|
+ Commit and push this change to the the ``anouncements.json`` file to
|
|
|
2028
|
+ the upstream website repository, and gitlab will take care of automatically
|
|
|
2029
|
+ updating the website accordingly.
|
|
|
2030
|
+
|
|
|
2031
|
+* Regenerate BuildStream documentation
|
|
|
2032
|
+
|
|
|
2033
|
+ In order to update the badges we use in various documentation
|
|
|
2034
|
+ which reflects what is the latest stable releases and the latest
|
|
|
2035
|
+ development snapshots, we simply need to ensure a pipeline runs
|
|
|
2036
|
+ for the master branch in the BuildStream repository.
|
|
|
2037
|
+
|
|
|
2038
|
+ You can do this by using the "Run Pipeline" feature on the
|
|
|
2039
|
+ `pipelines page in the gitlab UI <https://gitlab.com/BuildStream/buildstream/pipelines>`_.
|
