0 Fork 0

mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2026-11-06 19:01:54 +00:00

Files

T

kevinveenbirkenbachandClaude Opus 4.7 98457f98fd refactor(update): unify version bumpers under utils/update + cli/contributing/update + scripts/github/update

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>

2026-05-15 20:12:07 +02:00

2.7 KiB

Raw Blame History

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.

For test commands and testing standards, see testing.md.

2.7 KiB Raw Blame History