From e03a6f3cdb0b6c39ffcb89d995627bfd61f1b7d1 Mon Sep 17 00:00:00 2001 From: Matthew Gilliard Date: Wed, 30 Jul 2014 08:55:59 +0100 Subject: [PATCH] Add first draft of HACKING.rst Consistent style is a highly-desirable feature of a codebase. There seems to be a recognition of this in review comments, but there is no guidance for what style should be consistently used. This patch attempts to document our conventions. It is presented as a file in the working tree rather than a spec. This is modelled after the approach taken in the nova project and others. I expect other TripleO repos to link back to this file rather than contain their own hacking rules. In order to ease the creation of this doc, I have tried to only include uncontentious guidelines. Discussion on additional items will be most productive on follow-on commits. Change-Id: Ice8c36f8d10b289aeebab01a19c6035a1be85422 --- HACKING.rst | 49 ++++++++++++++++++++++++++++++++++++++++++ doc/source/HACKING.rst | 1 + doc/source/index.rst | 1 + 3 files changed, 51 insertions(+) create mode 100644 HACKING.rst create mode 100644 doc/source/HACKING.rst diff --git a/HACKING.rst b/HACKING.rst new file mode 100644 index 00000000..a0d595a8 --- /dev/null +++ b/HACKING.rst @@ -0,0 +1,49 @@ +TripleO Style Guidelines +======================== + +- Step 1: Read the OpenStack Style Guidelines [1]_ +- Step 2: Read Bashate [2]_ +- Step 3: Read on + +TripleO Specific Guidelines +----------------------------- + +There is plenty of code that does not adhere to these conventions currently. +However it is useful to have conventions as consistently formatted code is +easier to read and less likely to hide bugs. New code should adhere to these +conventions, and developers should consider sensible adjustment of existing +code when working nearby. + +Spacing and Indentation +~~~~~~~~~~~~~~~~~~~~~~~ +Please follow conventions described in OpenStack style guidelines [1]_ and Bashate [2]_. + +Bash +~~~~ +As well as those rules described in Bashate [2]_: + +- The interpreter is ``/bin/bash``. +- Provide a shebang ``#!/bin/bash`` if you intend your script to be run rather than sourced. +- Use ``set -e`` and ``set -o pipefail`` to exit early on errors. +- Use ``set -u`` to catch typos in variable names. +- Use ``$()`` not `````` for subshell commands. +- Avoid repeated/copy-pasted code. Make it a function, or a shared script, etc. + +Script Input +~~~~~~~~~~~~ +- Avoid environment variables as input. Prefer command-line arguments. +- If passing structured data, use JSON. +- Avoid passing substantial amounts of bare data (eg JSON) on the command + line. It is preferred to place the data in a file and pass the filename. + Using process substitution ``<()`` can help with this. + +Variables +~~~~~~~~~ +- Within a shell script, variables that are defined for local use should be + lower_cased. Variables that are passed in or come from outside the script + should be UPPER_CASED. + +References +---------- +.. [1] http://docs.openstack.org/developer/hacking/ +.. [2] http://git.openstack.org/cgit/openstack-dev/bashate/tree/README.rst diff --git a/doc/source/HACKING.rst b/doc/source/HACKING.rst new file mode 100644 index 00000000..a2bcf4fd --- /dev/null +++ b/doc/source/HACKING.rst @@ -0,0 +1 @@ +.. include:: ../../HACKING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index fbc43753..308cffc4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,6 +9,7 @@ Getting Started README userguide devtest + HACKING Detailed notes ---------------