zuul/zuul-jobs
Code Issues Proposed changes

Merge "Add guidelines on variable naming"

Browse Source
This commit is contained in:
Zuul
2018-09-06 02:12:06 +00:00
committed by Gerrit Code Review
parent f0cff4d4e9 c9b4b01187
commit ef98aba00a
2 changed files with 31 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/index.rst
View File

@@ -4,7 +4,7 @@
:maxdepth: 1 :maxdepth: 1
install install
deprecation policy
jobs jobs
roles roles

34
doc/source/deprecation.rst → doc/source/policy.rst
View File

@@ -1,5 +1,13 @@
Policy
======
Below are some guidelines for developers contributing to `zuul-jobs`.
.. contents::
:local:
Deprecation Policy Deprecation Policy
================== ------------------
Because `zuul-jobs` is intended for wide use by any Zuul, we try to Because `zuul-jobs` is intended for wide use by any Zuul, we try to
take care when making backwards incompatible changes. 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). fork of `zuul-jobs` (or stop updating it if you already have).
New Zuul Features New Zuul Features
----------------- *****************
When a new feature is available in Zuul, the jobs in `zuul-jobs` may 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 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. a change to `zuul-jobs` which uses it.
Deprecated Zuul Features Deprecated Zuul Features
------------------------ ************************
Before deprecating a feature in Zuul which is used by `zuul-jobs`, the 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 usage of the feature must be removed from `zuul-jobs` according to the
deprecation policy described above. deprecation policy described above.
Python Version Policy Python Version Policy
===================== ---------------------
``zuul-jobs`` targets Python 2.7 onwards and Python 3.5 onwards (note ``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 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 some tips on this in `Ansible and Python 3
<https://docs.ansible.com/ansible/2.5/dev_guide/developing_python_3.html>`__. <https://docs.ansible.com/ansible/2.5/dev_guide/developing_python_3.html>`__.
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-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 .. _zuul-discuss: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-discuss