Add installation/deprecation documentation

Change-Id: I4db13e723c90628ef2e3a48ba5758a04d75b8d5c
This commit is contained in:
James E. Blair 2018-04-11 08:03:57 -07:00
parent c5fc057417
commit af0d8eb25b
4 changed files with 80 additions and 2 deletions

View File

@ -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.

View File

@ -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

View File

@ -1,9 +1,10 @@
.. include:: ../../README.rst
.. toctree::
:maxdepth: 2
:maxdepth: 1
install
deprecation
jobs
roles

37
doc/source/install.rst Normal file
View File

@ -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