From c9b4b01187cbdcc86f01b896c4c7a05737771c8f Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Fri, 24 Aug 2018 10:56:39 +1000 Subject: [PATCH] Add guidelines on variable naming This captures some discussion over the scoping of variable names during some recent role development. It tries to provide some guidelines to prefixing of global variable names in roles and "module-like" roles. Since "deprecation.rst" is now holding a few different things, it makes more sense as "policy.rst". Reorganise to be nested in one more level, and add a contents section to help find sections easier. Change-Id: I0d551eefd33744ffa23418d0780769a7e52fe9cf --- doc/source/index.rst | 2 +- doc/source/{deprecation.rst => policy.rst} | 34 +++++++++++++++++++--- 2 files changed, 31 insertions(+), 5 deletions(-) rename doc/source/{deprecation.rst => policy.rst} (72%) diff --git a/doc/source/index.rst b/doc/source/index.rst index 93d2263ab..72ca4408d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -4,7 +4,7 @@ :maxdepth: 1 install - deprecation + policy jobs roles diff --git a/doc/source/deprecation.rst b/doc/source/policy.rst similarity index 72% rename from doc/source/deprecation.rst rename to doc/source/policy.rst index aab28b74d..dfb8c894d 100644 --- a/doc/source/deprecation.rst +++ b/doc/source/policy.rst @@ -1,5 +1,13 @@ +Policy +====== + +Below are some guidelines for developers contributing to `zuul-jobs`. + +.. contents:: + :local: + Deprecation Policy -================== +------------------ Because `zuul-jobs` is intended for wide use by any Zuul, we try to take care when making backwards incompatible changes. @@ -16,7 +24,7 @@ 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 @@ -26,14 +34,14 @@ 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. Python Version Policy -===================== +--------------------- ``zuul-jobs`` targets Python 2.7 onwards and Python 3.5 onwards (note this differs slightly from Ansible upstream, where the policy is 2.6 @@ -44,6 +52,24 @@ Library code should be written to be compatible with both. There are some tips on this in `Ansible and Python 3 `__. +Role Variable Naming Policy +--------------------------- + +Variables referenced by roles from global scope (often intended to be +set via ``host_vars`` and ``group_vars``, but also set during role +inclusion) must be namespaced by prepending their role-name to the +variable. Thus ``example-role`` would have variables with names such +as ``example_role_variable``; e.g. + +.. code-block:: yaml + + tasks: + - name: Call "example" role + include_role: + name: example-role + vars: + example_role_variable: 'something' + .. _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