grenade/HACKING.rst

Grenade Coding Guide

General

Grenade is written in POSIX shell script. It specifies BASH and is compatible with Bash 3.

Grenade's official repository is located at https://opendev.org/openstack/grenade.

Scripts

Grenade scripts should generally begin by calling env(1) in the shebang line:

#!/usr/bin/env bash

The script needs to know the location of the Grenade install directory. GRENADE_DIR should always point there, even if the script itself is located in a subdirectory:

# Keep track of the current grenade directory.
GRENADE_DIR=$(cd $(dirname "$0") && pwd)

Many scripts will utilize shared functions from the functions file. This file is copied directly from DevStack trunk periodically. There is also an rc file (grenaderc) that is sourced to set the default configuration of the user environment:

# Keep track of the current grenade directory.
GRENADE_DIR=$(cd $(dirname "$0") && pwd)

# Import common functions
source $GRENADE_DIR/functions

# Import configuration
source $GRENADE_DIR/grenaderc

Documentation

The GitHub repo includes a gh-pages branch that contains the web documentation for Grenade. This is the primary Grenade documentation along with the Grenade scripts themselves.

All of the scripts are processed with shocco to render them with the comments as text describing the script below. For this reason we tend to be a little verbose in the comments _ABOVE the code they pertain to. Shocco also supports Markdown formatting in the comments; use it sparingly. Specifically, grenade.sh uses Markdown headers to divide the script into logical sections.