Best Practices

Prefer consistency in documentation and update if file is touched.

Always resolve yamllint, and ansible-lint issues with no global exceptions (example).

Use ansible sourced jinja2 templates for release cycles faster than Debian

Many modern applications use rolling release or rapid release cycles in the span of months ➔ weeks ➔ days. Many of these updates have breaking config setting changes requiring complete re-evaluation of application under management when encapsulating configuration settings.

This is untenable for maintaining large numbers of roles.

Any application where major releases (or breaking releases) occur faster than the Debian release cycle must use ansible source jinja2 templates for configuration. This enables the role to focus on critical setup and the consumer to configure the application settings appropriately.

See Templated Directories.

Use Data annotations for variables touched by consumer (example) that require data manipulation for role application.
Always create roles explicitly designed for bare-metal installations.
Use feature flags to stage role execution steps.
Provide debug notification & estimated wait time with glyphs for long running tasks (example).

Always include update date, version, and OS release in vars/main.yml:

{ROLE}___release: "{{ {} | r_pufky.data.v3(

    _date='2024-06-14',
    _debian='bookworm',
    _app='1.20.20',
  )}}"

{ROLE}___packages:
  - 'ssh'

Format Rules

See style guide.

Style	Rule
80	Character width.
2	Spaces per tab.
2	Spaces - nested section.
4	Spaces - extended text from previous line.
1	Vertical space between sections.
.	All lines end in `.` for complete statement unless exactly 80.
#	Comment - all lines end in `.` unless exactly 80.
Tense	Always use present active tense for concise documentation.

Naming Conventions

Style	Rule
`var_name`	Variables are unquoted in paragraphs.
`{ROLE}___{VAR}`	Role variable.
`{ROLE}___{VAR}`	Role runtime variable.
*`^${VAL}`**	regex expressions are allowed; use
`N/A`	not applicable
`':'`	Always quote to disambiguate separators.

Abbreviated Data Types

Type	Default
`int`	`#` (not empty).
`float`	`#.#` (not empty).
`bool`	`True` or `False` (not empty).
`str`	`''`
`list`	`[]`
`dict`	`{}`
`{TYPE} of {TYPE}`	Outer most type first (e.g. list of str - `[]`).
`{TYPE} or {TYPE}`	Multiple types - preferred type first.

TODO

Place anywhere where additional work is needed. No restrictions.

# TODO(bug): List deletion via API is currently broken. This is fixed in the
#     next PiHole release. Lists will still be managed, but cannot be deleted.
# ⋮ Good TODO categories: bug, role, user, {VERSION}.

⋮ Alternative Context

Include alternative docstring format or context inline with the docstring option. This provides self-documenting expanded use features.

# Requires role_other_option=true.
# ⋮Requires:
# ⋮* multi_option_one='value'.
# ⋮* multi_option_two=true.

Text Glyphs

Glyph	Code	Use
➔	2794	Menus, sub-items, links.
⚠	26a0	Warning.
ⓘ	24be	Informational.
🗘	1f5d8	Waiting.
✔	2714	Success / Enabled.
✘	2718	Failure / Disabled.
⋮	22ee	Additional context (or context menu).
⚙	2699	Settings.
⌘	2318	Super key.