CODINGSTYLE.md: Expand and rewrite largely

These changes were originally proposed as an alternative to the previous
codingstyle document. Some Alpine contributors preferred the document
version proposed by myself. As such this change overwrites the previous
version of the codingstyle document.

1 files changed, 173 insertions, 95 deletions

diff --git a/CODINGSTYLE.md b/CODINGSTYLE.md
index 74dfcd154e..7f24ca43fa 100644
--- a/CODINGSTYLE.md
+++ b/CODINGSTYLE.md
@@ -1,111 +1,189 @@
-# Alpine Linux coding style
-
-Thank you for taking interest in contributing to our aports repository.
-As consistency and readability are so important for the quality of our APKBUILD
-and thus the quality of Alpine Linux, we kindly ask to follow these
-recommendations.
-
-## Language
-Alpine Linux APKBUILD files are inherently just POSIX shell scripts. Please avoid
-extensions, even if they work or are accepted by busybox ash. (using keyword
-`local` is an exception)
-
-## Naming convention
-Use snake_case. Functions, variables etc. should be lower-cased with
-underscores to separate words.
-
-Local 'private' variables and functions in global scope should be prefixed
-with a single underscore to avoid name collisions with internal variables in
-`abuild`.
-
-Double underscores are reserved and should not be used.
-```sh
-_my_variable="data"
-```
-
-### Bracing
-Curly braces for functions should be on the same line.
-
-```sh
-prepare() {
-        ...
-}
-```
-
-Markers to indicate a compound statement should be on the same line.
-
-
-#### if ...; then
-```sh
-        if [ true ]; then
-                echo "It is so"
-        fi
-}
-```
-
-#### while ...; do
-```sh
-        while ...; do
-                ...
-        done
-```
-
-#### for ...; do
-```sh
-        for x in foo bar baz; do
-                ...
-        done
-```
+# Policy for APKBUILDs
 
-### Spacing
-All keywords and operators are separated by a space.
+This documents defines a policy for writing APKBUILDs.
+
+# Standard selection
+
+APKBUILDs are POSIX shell scripts as defined in [POSIX.1-2017 Volume 3]
+[POSIX.1-2017 volume 3]. Additionally, the following extensions are
+supported:
+
+1. The `local` keyword for introducing variables local to a function is
+   supported, it is briefly documented in the [bash manual][bash functions].
+2. Non-POSIX [parameter extensions][POSIX.1-2017 parameter expansion]
+   are supported.  This includes: Substring expansions (e.g.
+   `${var:offset:length}`) and Replacement expansions (e.g.
+   `${var/pattern/string}`). The [bash manual][bash expansion]
+   contains further information on these two expansions.
+
+**NOTE:** `busybox ash` is currently used to evaluate APKBUILDs since it
+supports additional POSIX shell extensions your APKBUILD might be
+evaluated correctly even if it is not confirming to this policy
+document.
+
+# Shell Style Considerations
+
+<!--
+This should be in conformance with most existing APKBUILDs
+Structure and content inspired by Google Shell Style Guide.
+-->
+
+## Formatting
+
+### Indention
+
+Indent with tabs, don't use spaces. Avoid whitespaces.
+
+### Line Length
+
+Maximum line length is 80 characters, this should be considered a
+recommendation and not a string requirement which must be followed at
+all costs. Most notably, automatically generated parts (e.g. by `abuild
+checksum`) are except from this rule.
+
+### Compound Statements
 
-For cleanliness sake, ensure there is no trailing whitespace.
+Put `; do` and `; then` on the same line as the `while`, `for` or `if`.
 
-## Identation
-Indentation is one tab character per level, alignment is done using spaces.
-For example (using the >------- characters to indicate a tab):
-```sh
-build()
-{
->-------make DESTDIR="${pkgdir}" \
->-------     PREFIX="/usr"
-}
-```
+### Function Declarations
 
-This ensures code is always neatly aligned and properly indented.
+* Always put the function name, the parenthesis and the curly brackets
+  on the same line.
+* Don't use spacing between function name and parenthesis.
+* Do use spacing between function parenthesis and curly brackets.
 
-Space before tab should be avoided.
+### Case statement
 
-## Line length
-A line should not be longer than 80 characters. While this is not a hard limit, it
-is strongly recommended to avoid having longer lines, as long lines reduce
-readability and invite deep nesting.
+* Don't indent alternatives.
+* A one-line alternative needs a space after the close parenthesis of the pattern and before the `;;`.
 
-## Variables
+### Variable expansion
+
+* Use `${var}` over `$var` only when it is strictly necessary. Meaning:
+  Only if the character following the [variable name][POSIX.1-2017 definition name]
+  is an underscore or an alphanumeric character.
 
 ### Quoting
-Quote strings containing variables, command substitutions, spaces or shell meta
-characters, unless careful unquoted expansion is required.
 
-Don't quote _literal_ integers.
+* Always quote string literals (exceptions are assigning `pkgname` and
+  `pkgver`, more on this below).
+* Always quote variables, command substitutions or shell meta characters
+  when used in strings. Prefer `"$var"/foo/bar` over `"$var/foo/bar"`.
+* Never quote literal integers.
+
+## Features
+
+### Command Substitution
+
+* Always use `$()` instead of backticks.
+
+### Test and [
+
+* Prefer `[` over `test(1)`.
+
+## Naming Conventions
+
+### Function Names
+
+* Lower-case, with underscores to separate words. Prefix all helper
+  functions with an underscore character.
+
+### Variable Names
+
+* Lower-case, with underscores to separate words. Prefix all
+  non-metadata variables with an underscore character.
+
+### Use Local Variables
+
+*  Declare function-specific variables with the `local` keyword.
+
+## Calling Commands
+
+### Command Substitutions and Global Variables
+
+* Avoid command Substitutions in global variables, use parameter
+  expansions instead.
+
+### Return Values
+
+* APKBUILDs are executed with `set -e`, explicit `|| return 1`
+  statements must not be used.
+
+## Comments
+
+### Spacing
+
+* All comments begin with an ASCII space character, e.g. `# foo`.
+
+### TODO Comments
+
+* Use TODO comments for code that is temporary, a short-term solution,
+  or good-enough but not perfect.
+
+# APKBUILD style considerations
+
+<!--
+This section attempts to document policies enforced by the linter from
+atools <https://github.com/maxice8/atools>, newapkbuild and existing
+APKBUILDs.
+-->
+
+## Comments
+
+### Contributor Comment
+
+* All APKBUILDs begin with one or more contributor comments (one per
+  line) containing a valid [RFC 5322][RFC 5322] address. For example,
+  `# Contributor: Max Mustermann <max@example.org>`.
+
+### Maintainer Comment
+
+* All APKBUILDs contain exactly one maintainer comment containing a
+  valid RFC 5322 address. For example, `# Maintainer: Max Mustermann
+  <max@example.org>`.
+* In addition to a Maintainer Comment a Contributor Comment must be
+  present for said Maintainer.
+
+## Metadata Variables
+
+Metadata Variables are variables used directly by abuild itself, e.g. `pkgname` or `depends`.
+
+### Metadata Values
+
+* `pkgname` must only contain lowercase characters.
+* `pkgname` must match the name of the directory the `APKBUILD` file is located in.
+
+### Variable Assignments
+
+* Empty Metadata Variable assignments, e.g. `install=""` must be removed.
+* The Metadata Variable `builddir` defaults to `$srcdir/$pkgname-$pkgver`
+  and should only be assigned if the default values is not appropriate.
+
+### Assignment Order
+
+* All Metadata Variables (except checksums) must be declared before the
+  first function declaration.
+* Checksum Metadata Variables must be declared after the last function
+  declaration, `abuild checksum` will automatically take care of this.
 
-### Bracing
-Only use curly braces around variables when needed.
+## Build Functions
 
-```sh
-foo="${foo}_bar"
-foo_bar="$foo"
-```
+### Function Declaration
 
-## Subshell usage
-Use `$()` syntax, not backticks.
+* Functions should be declared in the order they are called by abuild.
+* All functions are executed in `"$builddir"` explicit directory changes
+  to `$builddir` must be avoided (if possible).
+* Variables local to functions must always be declared with the `local`
+  keyword.
 
-## Sorting
-Some items tend to benefit from being sorted. A list of sources, dependencies
-etc. Always try to find a reasonable sort order, where alphabetically tends to
-be the most useful one.
+### Function Overwriting
 
-## Eval
-`eval` is evil and should be avoided.
+* If the `prepare` function is overwritten it should always call
+  `default_prepare`.
 
+[POSIX.1-2017 volume 3]: https://pubs.opengroup.org/onlinepubs/9699919799/idx/xcu.html
+[POSIX.1-2017 parameter expansion]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_02
+[POSIX.1-2017 definition name]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_235
+[bash functions]: https://www.gnu.org/software/bash/manual/bash.html#Shell-Functions
+[bash expansion]: https://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion
+[RFC 5322]: https://tools.ietf.org/html/rfc5322