mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 02:54:26 +00:00
kevinveenbirkenbachandClaude Opus 4.7
98457f98fd
Folds the parallel Docker-image and git-ref version-update plumbing
into a single subsystem so the auto-update workflow, the external
freshness tests, and the unit tests all share one module layout.
utils/
update/
base.py # semver primitives shared by both backends
docker.py # OCI registry lookups + version: line rewriter
repository.py # git ls-remote walker + ref: line rewriter
cli/contributing/update/
docker/ # python -m cli.contributing.update.docker
repository/ # python -m cli.contributing.update.repository
scripts/github/update/
image_versions.sh
repository_refs.sh
Tests mirror the same shape under tests/{unit,external}/update/{docker,repository}/.
Also widens the Docker bump scope to all roles (previously gated on
`web-*`) so non-web roles like sys-svc-container get bumped too;
pins Bookwyrm's python image at 3.11-bookworm via
`# nocheck: docker-version` with a TODO until upstream supports
Python >= 3.12.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
51 lines
2.7 KiB
Markdown
51 lines
2.7 KiB
Markdown
# Ansible 🎭
|
|
|
|
Use this section for Ansible-specific guidance that applies across the repository.
|
|
|
|
## Common 📌
|
|
|
|
Use these shared rules as the default baseline for role values and path handling.
|
|
|
|
## Paths 📂
|
|
|
|
You MUST build filesystem paths with `path_join` instead of concatenating path segments as strings.
|
|
|
|
## Variables and Constants 🔧
|
|
|
|
These rules keep shared role values explicit, reusable, and easy to read.
|
|
|
|
- You MUST prefer defining shared fixed role variables once in `vars/main.yml` as the single source of truth instead of recomputing them with `lookup()` or dotted variable composition in `*.j2` or `*.yml`.
|
|
- Variables that are defined once and treated as constants MUST be uppercase.
|
|
|
|
## Role Design 🏗️
|
|
|
|
Use this section for role-structure guidance around images, files, and constants.
|
|
|
|
### Container Images 🐳
|
|
|
|
Use this rule when a role needs a Docker image definition.
|
|
|
|
- You SHOULD prefer `Dockerfile` over `Dockerfile.j2`; only use `Dockerfile.j2` when build-time templating is genuinely required.
|
|
|
|
### Image Versions 🏷️
|
|
|
|
Use this rule when a role pins container image versions in `roles/*/meta/services.yml`.
|
|
|
|
- You MUST keep semver-like image versions current when the upstream image publishes matching newer tags.
|
|
- You MUST use `# nocheck: docker-version` directly above a `version:` key only for intentional exceptions that should not be flagged by the external image-version check.
|
|
- You SHOULD prefer explicit version pinning over drifting tags when the role depends on stable, reproducible deploys.
|
|
|
|
### Extracted Code 📤
|
|
|
|
Use this rule when a task body contains non-trivial shell, SQL, Python, JavaScript, or any other non-YAML code.
|
|
|
|
- You MUST extract non-trivial non-YAML code out of task files into a dedicated role asset instead of inlining it:
|
|
- Static scripts (shell, Python, binaries) belong in `roles/<role>/files/<name>.<ext>` and are invoked via `ansible.builtin.script` or `command`.
|
|
- Rendered code (SQL, JSON, JS, config snippets, env files) belongs in `roles/<role>/templates/<name>.<ext>.j2` and is consumed via `lookup('template', '<name>.<ext>.j2')` (for inline values) or `ansible.builtin.template` (for file deployment).
|
|
- The reason is reviewability and tooling. Extracted assets get proper syntax highlighting, linting, and diffing. Inline heredocs and multi-line `query:` or `command:` blocks hide all three and make the task file harder to read.
|
|
- One-liners such as a single `command:` or a short `shell:` pipeline MAY stay inline. The rule targets bodies that are themselves a program, not every shell call.
|
|
|
|
For documentation, comments, semantics, and writing guidance, see [documentation.md](../documentation.md).
|
|
|
|
For test commands and testing standards, see [testing.md](../actions/testing.md).
|