Commit a01adcab authored by Benjamin Tissoires's avatar Benjamin Tissoires
Browse files

ci-fairy: document extends, include and version



Take the docs from the current class, and prettify them a little bit.
Signed-off-by: Benjamin Tissoires's avatarBenjamin Tissoires <benjamin.tissoires@gmail.com>
parent d57148ef
......@@ -271,6 +271,98 @@ Example:
'.gitlab-ci/fedora-install.sh'))[0:12]
}}'
Extensions to YAML syntax:
..........................
In addition to the ``ci_fairy`` or ``🧚`` keyword, some keywords have been added to the
YAML language to allow easier configuration.
extends:
^^^^^^^^
``extends`` aims at replicating `Gitlab CI/CD extends keyword <https://docs.gitlab.com/ce/ci/yaml/#extends>`_.
There are a few differences however, and ``ci-fairy`` only supports the following:
Supported in: top-level dictionaries
The ``extends:`` keyword makes the current dictionary inherit all
members of the extended dictionary, according to the following rules:
- where the value is a non-empty dict, the base and new dicts are merged
- where the value is a non-empty list, the base and new list are concatinated
- where the value is an empty dict or empty list, the new value is the empty dict/list.
- otherwise, the new value overwrites the base value.
Example:
.. code-block:: yaml
foo:
bar: [1, 2]
baz:
a: 'a'
b: 'b'
bat: 'foobar'
subfoo:
extends: bar
bar: [3, 4]
baz:
c: 'c'
bat: 'subfoobar'
Results in the effective values for subfoo:
.. code-block:: yaml
subfoo:
bar: [1, 2, 3, 4]
baz: {a: 'a', b: 'b', c: 'c'}
bat: 'subfoobar'
foo:
bar: 1
include:
^^^^^^^^
``include`` aims at replicating the local include from `Gitlab CI/CD include keyword <https://docs.gitlab.com/ce/ci/yaml/#include>`_.
Supported in: top-level only
The ``include:`` keyword includes the specified file at the place. The
path to the included file is relative to the source file.
Example:
.. code-block:: yaml
# content of firstfile
foo:
bar: [1, 2]
#content of secondfile
bar:
baz: [3, 4]
include: firstfile
foobar:
extends: foo
.. note:: the included file will work with the normal YAML rules,
specifically: where the included file has a key with the same name this
section will be overwritten with the later-defined. The position of the
``include`` statement thus matters a lot.
version:
^^^^^^^^
The YAML file version (optional). Handled as attribute on this object and does not
show up in the dictionary otherwise. This version must be a top-level
entry in the YAML file in the form "version: 1" or whatever integer
number and is exposed as the "version" attribute.
Where other files are included, the version of that file must be
identical to the first version found in any file.
.. _ci-fairy-commit-checks:
Checking commits
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment