Guide Review Checklist

We use this checklist when reviewing pull requests from our users that add or change guides. Compare every new or changed guide against docs/meta/boilerplate. The authoritative style rules for contributors live in contributing.md.

Boilerplate comparison

Open docs/meta/boilerplate side by side with the guide in the PR. The guide should follow the same skeleton. Mandatory sections must be present; optional sections may be omitted when they do not apply.

Boilerplate element	What we check
Front matter	Same fields as boilerplate: render_macros, title, logo, authors, tags, website, license, tested with nested app and uberspace
Logo path	_static/images/guides/<app>.(svg|png) — boilerplate uses guides/ subdirectory
Authors block	YAML list with - name:; email and/or url included where possible
Header include	{% include 'guide_header.md' %} on line 1 after closing ---
Opening paragraph	Mandatory — short app description before the first section separator
Section separator	---- (four dashes) before the prerequisites note and between major sections
Prerequisites note	!!! note with “For this guide you should be familiar with the basic concepts of:” and bullet list of manual links — present when a Prerequisites section is used
## Prerequisites	Optional — runtime versions (PHP, etc.) and MariaDB credentials via my_print_defaults client when a database is used
## Installation	Mandatory — step-by-step commands in console-remote blocks; starts from /var/www/virtual/$USER/html/ unless the app requires a different layout (with justification)
## Configuration	Optional — post-install setup separate from installation
## Tuning	Optional — performance or convenience improvements
## Debugging	Optional — where to look when things break
## Updates	Mandatory — starts with !!! note linking to an RSS/Atom release feed, then update steps
## Further Reading	Optional — bullet list of links for debugging, advanced configuration, and deeper documentation
Prompt style	[isabell@moondust ~]$ on first line; working directory reflected in subsequent prompts (e.g. [isabell@moondust html]$)
MariaDB in prose	Boilerplate links to MariaDB, not MySQL

For new guides, we diff against the boilerplate:

# Replace appname with the guide slug (e.g. contao)
diff -u docs/meta/boilerplate docs/guide_appname.md | less

We call out structural differences (missing sections, extra headings, wrong separator length) in our review unless the contributor justified them.

Quick checks

We run these from the repository root before or during review. The script covers tag registration, mandatory structure, front matter, logo paths, and the pattern checks below.

# Changed guides in the PR branch
./hooks/check_guide.sh --changed

# Explicit file(s)
./hooks/check_guide.sh docs/guide_appname.md

# Staged guides only
./hooks/check_guide.sh --staged

# All guides
./hooks/check_guide.sh --all

# Treat consistency warnings as errors
./hooks/check_guide.sh --changed --strict

Issues are reported as MUST (blocking) or SHOULD (consistency). The script uses uv run python when available; otherwise python3 with PyYAML is required.

For manual spot checks or debugging, the same patterns are available via rg:

# Wrong hostname in shell prompts (should be moondust, not stardust or others)
rg '\[isabell@[^m]' docs/guide_*.md
rg 'stardust' docs/guide_*.md

# Hardcoded username in paths (prefer $USER)
rg '/var/www/virtual/isabell/' docs/guide_*.md

# Disallowed heredoc pattern
rg 'cat > .* <<' docs/guide_*.md

# tested.uberspace with v prefix (should be 8.0.x without v)
rg 'uberspace: "v' docs/guide_*.md

Prompt and MariaDB wording checks are handled by hooks/check_guide.py (smarter than a plain rg pattern).

Metadata

Every submitted guide must start with YAML front matter matching docs/meta/boilerplate.

Field	What we check
render_macros	Must be true
title	Application name
logo	Path exists under docs/_static/images/ (SVG preferred, PNG with transparent background)
authors	At least name; url or email for Hall of Fame
tags	Existing tags from mkdocs.yml → extra.tag_descriptions; we add new tags there if needed
website	Official project URL
license	Application license (e.g. GPLv2, AGPLv3)
tested.app	Version the contributor actually tested on a fresh Asteroid
tested.uberspace	Uberspace version, format 8.0.x (no v prefix)

Header and structure

Rule	What we check
Guide header	{% include 'guide_header.md' %} immediately after front matter
Section order	Matches boilerplate order; mandatory sections (description, Installation, Updates) present; optional sections may be omitted when not applicable
Section separators	---- (four dashes) between major sections
Prerequisites note	Same pattern as boilerplate: !!! note with familiar-concepts intro and manual link bullets
Extra sections	Link collections use ## Further Reading; other extra headings are OK if they add value and are justified

Code blocks

Block type	Language tag	What we check
Uberspace server	console-remote	Username isabell, hostname moondust, prompt [isabell@moondust ~]$ (always include trailing $)
Local machine	console	Reader's local prompt, e.g. [localuser@localhost ~]$
Config files	ini, yaml, etc.	Appropriate language identifier

Content

Rule	What we check
Language	English (en_US)
Document root	/var/www/virtual/$USER/; empty document root assumed
Paths	Full paths; no home directory shortcuts like ~/www
Subfolders	Avoided unless the application requires them; justification present if used
Database	mariadb command and “MariaDB” in prose; my_print_defaults client when credentials are needed
Database names	${USER}_appname convention
Shell output	Command output included when it helps the reader
Flags	Non-obvious options explained; long forms preferred (--verbose)
Default passwords	Reader told to change them
File editing	No cat > file <<EOF; reader told to edit files
Logs	Symlink to ~/logs when the app writes logs
Updates	Matches boilerplate: !!! note with release feed link, then update instructions
Internal links	Relative paths, e.g. [WordPress guide](../guide_wordpress.md)
Manual links	Absolute URLs to https://u8manual.uberspace.de/...

Admonitions

Guides use Material admonitions (!!! note, !!! warning, !!! tip) for important information. Prerequisites and update feeds use !!! note.

Commit messages

Contributors prefix commit subjects with [appname], e.g. [wordpress] add update info. New guide: [appname] add guide. Repo/meta work: [meta] …. Codeberg issue titles use the same [appname] or [meta] prefix. Apply type/triage labels per contributing.md — Labels.

After merge

Merged pull request branches are deleted automatically by .forgejo/workflows/delete-merged-branch.yaml (requires Actions enabled). main is never deleted. Fork head branches are skipped.

Review outcome template

When we leave feedback on a contributor's PR, we group findings by severity:

1. Must fix — Violates contributing rules; guide would mislead users or fail on a fresh Asteroid
2. Should fix — Consistency issues (prompts, paths, terminology) that do not block correctness
3. Optional — Naming, structure, or polish suggestions

We confirm the contributor tested all steps on a fresh Uberspace 8 Asteroid before we approve.