commit to some level of style in variable naming

This is an ugly patch, and probably does more than I'd like it to. The
idea is that mkinitcpio adopts some sort of consistent style which I'm
actually happy with. I define 3 kinds of variables:

1) local variables: all lower case, and scoped within functions. Use
freely, as they're well contained.

2) global variables: these are known to mkinitcpio internally, but are
global in scope. They mainly carry runtime configuration and collected
data during the image generation process. These are always lower case,
but carry a leading underscore to denote that they're global.

3) "API" variables: also global in scope, but exist "outside" of
mkinitcpio -- either drawn in from the configuration file, or "exported"
to the install hooks. These are always all upper case. When introducing
new variables, extreme care must be taken to pick names that will not
conflict with the environment inherited by mkinitcpio.

A HACKING file is introduced with a similar description of the above,
and more.

Signed-off-by: Dave Reisner <dreisner@archlinux.org>

1 files changed, 67 insertions, 0 deletions

diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..774a03d
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,67 @@
+Care and feeding of your initramfs generator
+--------------------------------------------
+
+This guide attempts to outline the style used in the mkinitcpio codebase.
+
+
+Bash v. POSIX
+-------------
+Never use POSIX syntax if Bash offers a construct of its own, even if the
+two are effectively identical. This means always using double braces over
+the inferior '[' and 'test'.
+
+
+Variable usage and naming convetions
+------------------------------------
+There are three classifications of variables in mkinitcpio.
+
+1) local variables: all lower case, and scoped within functions. Use
+freely, as they're well contained. Unless you're introducing a new
+option, this is what you want to use.
+
+  local foo=$1
+
+2) global variables: these are known to mkinitcpio internally, but are
+global in scope. They carry runtime configuration and data collected during the
+image generation process. These are always lower case, but carry a leading
+underscore to denote that they're global. It's helpful to prefix these
+variables instead with a '_f_' or '_d_' if they refer to a file or directory,
+respectively.
+
+  _optcolor=1
+  _d_hookdir=/etc/foo.d
+  _f_config=/etc/foo.conf
+
+3) "API" variables: also global in scope, but exist "outside" of
+mkinitcpio -- either drawn in from the configuration file, or "exported"
+to the install hooks. These are always all upper case. When introducing
+new variables, extreme care must be taken to pick names that will not
+conflict with the environment inherited by mkinitcpio.
+
+Function naming
+---------------
+Use all lower case with underscores where appropriate, for easy readability.
+Adhere to POSIX variable naming requirements for the contents of the name,
+that is: only alphanumerics, underscores, and the identifier must not start
+with a number.
+
+
+Quoting
+-------
+Overquoting is preferred to underquoting, but freely avoid quoting in the
+cases when expansion is guaranteed not to happen, such as in single argument
+test expressions or the subject of a case statement.
+
+
+Functions and block statements
+------------------------------
+Always use "top-right, "lower left" for blocks of code and functions.
+
+  do_glob() {
+    local g fn=$1; shift
+
+    for g in "$@"; do
+      "$fn" "$g"
+    done
+  }
+