From af0d8eb25b63f320ed63500a51b287ed45bbbb1b Mon Sep 17 00:00:00 2001 From: "James E. Blair" Date: Wed, 11 Apr 2018 08:03:57 -0700 Subject: [PATCH] Add installation/deprecation documentation Change-Id: I4db13e723c90628ef2e3a48ba5758a04d75b8d5c --- README.rst | 3 +++ doc/source/deprecation.rst | 37 +++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 5 +++-- doc/source/install.rst | 37 +++++++++++++++++++++++++++++++++++++ 4 files changed, 80 insertions(+), 2 deletions(-) create mode 100644 doc/source/deprecation.rst create mode 100644 doc/source/install.rst diff --git a/README.rst b/README.rst index 1e6d5222e..8da5cd89e 100644 --- a/README.rst +++ b/README.rst @@ -3,3 +3,6 @@ Zuul Jobs This repo contains a set of Zuul jobs and Ansible roles suitable for use by any Zuul system. + +.. See the full documentation at https://zuul-ci.org/docs/zuul-jobs/ + for more information, including usage instructions. diff --git a/doc/source/deprecation.rst b/doc/source/deprecation.rst new file mode 100644 index 000000000..6d3fff3c1 --- /dev/null +++ b/doc/source/deprecation.rst @@ -0,0 +1,37 @@ +Deprecation Policy +================== + +Because `zuul-jobs` is intended for wide use by any Zuul, we try to +take care when making backwards incompatible changes. + +If we need to do so, we will send a notice to the `zuul-announce`_ +mailing list describing the change and indicating when it will be +merged. We will usually wait at least two weeks between sending the +announcement and merging the change. + +If the change affects your jobs, and you are unable to adjust to it +within the timeframe, please let us know with a message to the +`zuul-discuss`_ mailing list -- we may be able to adjust the +timeframe. Otherwise, you may wish to temporarily switch to a local +fork of `zuul-jobs` (or stop updating it if you already have). + +New Zuul Features +----------------- + +When a new feature is available in Zuul, the jobs in `zuul-jobs` may +not be able to immediately take advantage of it. We need to allow +time for folks to upgrade their Zuul installations so they will be +compatible with the change. In these cases, we will wait four weeks +after the first Zuul release with the required feature before merging +a change to `zuul-jobs` which uses it. + +Deprecated Zuul Features +------------------------ + +Before deprecating a feature in Zuul which is used by `zuul-jobs`, the +usage of the feature must be removed from `zuul-jobs` according to the +deprecation policy described above. + +.. _zuul-announce: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-announce +.. _zuul-discuss: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-discuss + diff --git a/doc/source/index.rst b/doc/source/index.rst index 092f1c1e9..93d2263ab 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,9 +1,10 @@ .. include:: ../../README.rst - .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + install + deprecation jobs roles diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 000000000..07af0ca16 --- /dev/null +++ b/doc/source/install.rst @@ -0,0 +1,37 @@ +Installation +============ + +To use this repository via continuous delivery, first ensure your Zuul +is configured to use git repositories from `git.zuul-ci.org`. Add the +following to ``zuul.conf``: + +.. code-block:: ini + + [connection zuul-git] + driver=git + baseurl=https://git.zuul-ci.org/ + +Then add the following to your tenant config file: + +.. code-block:: yaml + + - tenant: + name: ... + source: + zuul-git: + untrusted-projects: + - zuul-jobs + +Then restart Zuul. + +When changes merge into the `zuul-jobs` repository, your Zuul will +automatically update its configuration. + +If you would prefer to control when changes to `zuul-jobs` go into +production in your Zuul, simply fork your own copy of `zuul-jobs`, and +pull changes from upstream according to your own schedule. + +Subscribe to the `zuul-announce`_ mailing list to receive important +notices about changes to the `zuul-jobs` repository. + +.. _zuul-announce: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-announce