Skip to main content

Authoring scripts

Requirements​

note

Please refer to RFC2119 for meaning of words MUST, SHOULD and MAY.

  1. MUST adhere to POSIX standard.
  2. MUST pass Shellcheck code analysis scan
  3. MUST start with:
 #!/usr/bin/env bash
 ##
 # Action description that the script performs.
 #
 # More description and usage information with a last empty
 # comment line.
 #

 set -eu
 [ "${VORTEX_DEBUG-}" = "1" ] && set -x
  1. MUST list all variables with their default values and descriptions. i.e.:
# Deployment reference, such as a git SHA.
VORTEX_NOTIFY_REF="${VORTEX_NOTIFY_REF:-}"
  1. MUST include a delimiter between variables and the script body preceded and followed by an empty line (3 lines in total):
# ------------------------------------------------------------------------------
  1. SHOULD include formatting helper functions:
# @formatter:off
note() { printf "       %s\n" "${1}"; }
info() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[34m[INFO] %s\033[0m\n" "${1}" || printf "[INFO] %s\n" "${1}"; }
pass() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[32m[ OK ] %s\033[0m\n" "${1}" || printf "[ OK ] %s\n" "${1}"; }
fail() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[31m[FAIL] %s\033[0m\n" "${1}" || printf "[FAIL] %s\n" "${1}"; }
# @formatter:on
  1. SHOULD include variable values checks with errors and early exist, i.e.:
[ -z "${VORTEX_NOTIFY_REF}" ] && fail "Missing required value for VORTEX_NOTIFY_REF" && exit 1
  1. SHOULD include binaries checks if the script relies on them, i.e.:
command -v curl > /dev/null || ( fail "curl command is not available." && exit 1 )
  1. MUST contain an info message about the start of the script body, e.g.:
info "Started GitHub notification for operation ${VORTEX_NOTIFY_EVENT}"
  1. MUST contain an pass message about the finish of the script body, e.g.:
pass "Finished GitHub notification for operation ${VORTEX_NOTIFY_EVENT}"
  1. MUST use uppercase global variables
  2. MUST use lowercase local variables.
  3. MUST use long options instead of short options for readability. I.e., drush cache:rebuild instead of drush cr.
  4. MUST use VORTEX_ prefix for variables, unless it is a known 3-rd party variable like GITHUB_TOKEN or COMPOSER.
  5. MUST use script-specific prefix. I.e., for notify.sh, the variable to skip notifications should start with VORTEX_NOTIFY_.
  6. MAY rely on variables from the external scripts (not prefixed with a script-specific prefix), but MUST declare such variables in the header of the file.
  7. MAY call other Vortex scripts (discouraged), but MUST source them rather than creating a sub-process. This is to allow passing environment variables down the call stack.
  8. SHOULD use note messages for informing about the script progress.
  9. MUST use variables in the form of ${VAR}.

Variables​

Follow these guidelines when creating or updating Vortex variables.

  1. Local variables MUST be in lowercase, and global variables MUST be in uppercase.

  2. All Vortex variables MUST start with VORTEX_ to separate Vortex from third-party variables.

  3. Global variables MAY be re-used as-is across scripts. For instance, the WEBROOT variable is used in several scripts.

  4. Vortex action-specific script variables MUST be scoped within their own script. For instance, the VORTEX_PROVISION_OVERRIDE_DB variable in the provision.sh.

  5. Drupal-related variables SHOULD start with DRUPAL_ and SHOULD have a module name added as a second prefix. This is to separate Vortex, third-party services variables, and Drupal variables. For instance, to set a user for Drupal's Shield module configuration, use DRUPAL_SHIELD_USER.

  6. Variables SHOULD NOT be exported into the global scope unless absolutely necessary. Thus, values in .env SHOULD have default values set, but SHOULD be commented out to provide visibility and avoid exposure to the global scope.

Boilerplate script​

Use the boilerplate script below to kick-start your custom Vortex script.

#!/usr/bin/env bash
##
# Action description that the script performs.
#
# More description and usage information with a last empty
# comment line.
#

set -eu
[ "${VORTEX_DEBUG-}" = "1" ] && set -x

# Example Vortex variable with a default value.
VORTEX_EXAMPLE_URL="${VORTEX_EXAMPLE_URL:-http://example.com}"

# ------------------------------------------------------------------------------

# @formatter:off
note() { printf "       %s\n" "${1}"; }
info() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[34m[INFO] %s\033[0m\n" "${1}" || printf "[INFO] %s\n" "${1}"; }
pass() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[32m[ OK ] %s\033[0m\n" "${1}" || printf "[ OK ] %s\n" "${1}"; }
fail() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[31m[FAIL] %s\033[0m\n" "${1}" || printf "[FAIL] %s\n" "${1}"; }
# @formatter:on

info "Started Vortex operations."

[ -z "${VORTEX_EXAMPLE_URL}" ] && fail "Missing required value for VORTEX_EXAMPLE_URL" && exit 1
command -v curl >/dev/null || (fail "curl command is not available." && exit 1)

# Example of the script body.
curl -L -s -o /dev/null -w "%{http_code}" "${VORTEX_EXAMPLE_URL}" | grep -q '200\|403' && note "Requested example page"

pass "Finished Vortex operations."