emil
5b05db4e6d
Add /docs/ directory with user and technical documentation extracted from README, AGENTS.md, and source code. Add scripts/sync_wiki.py to sync docs to Gitea wiki via API. Add scripts/doc_coverage.py to check CLI commands, modules, and CI scripts are documented. Add sync-wiki.yml workflow for auto-sync on merge and release. Slim down README.md to lean entry point. 28 new unit tests, 100% coverage maintained. Closes GRM-36
5.1 KiB
Decision Log
Key technical decisions for the GRM project, extracted from CHANGELOG.md and AGENTS.md.
ADR-001: Dynamic Versioning via __init__.py
Date: 2026-06-21 (v0.2.0 unreleased)
Decision: Use dynamic = ["version"] in pyproject.toml with setuptools attr to source the version from __version__ in src/gitea_runner_manager/__init__.py.
Rationale: __init__.py is the single source of truth for the version. The release script (scripts/release.py) only updates __init__.py — there is no need to touch pyproject.toml. grm --version reports this version directly. This eliminates version duplication across files and ensures the runtime version always matches the tagged release.
Source: CHANGELOG.md (Unreleased — Added), AGENTS.md (Version Bumping Rules)
ADR-002: Rootless Docker per Runner
Date: Project inception (documented in README Architecture)
Decision: Each runner instance runs in an isolated rootless Docker environment under a dedicated system user (grm-<name>), with its own Docker socket at /run/user/<UID>/docker.sock.
Rationale: Rootless Docker per-runner avoids conflicts with the host's Docker installation and enables true parallel execution of multiple runners on the same host. Each instance has fully isolated resources: user, home, data directory, config directory, systemd user service, and Docker socket. This is a core feature of GRM — enabling multiple isolated runners on the same host.
Source: README.md (Architecture, Features), AGENTS.md (Architecture)
ADR-003: Conventional Commits + git-cliff for Automated Versioning
Date: 2026-06-21 (v0.2.0 unreleased)
Decision: Use conventional commits on feature branches and git-cliff (cliff.toml) to calculate the next semver version from commit history, generate the changelog, and automate releases.
Rationale: scripts/release.py uses git-cliff to calculate the next version from conventional commits since the last tag. Merge commits on master have the format GRM-N <conventional commit>, so cliff.toml includes a commit_preprocessors entry that strips the GRM-N prefix before parsing. Version bumping rules: feat: → minor, fix: → patch, feat!:/BREAKING CHANGE → minor (pre-1.0), chore:/ci:/docs: → no bump. This fully automates versioning and changelog generation.
Source: CHANGELOG.md (Unreleased — Added), AGENTS.md (Automated Release Pipeline, git-cliff Commit Preprocessing, Version Bumping Rules), cliff.toml
ADR-004: Enforce Tests Pass Before Tagging a Release
Date: 2026-06-21 (v0.2.2)
Decision: The release workflow runs make lint-ruff and make pytest-cov before creating a release commit or tag. If lint or tests fail, the release aborts immediately — no commit, no tag.
Rationale: This ensures every tagged release is healthy. A --skip-tests flag exists for emergency use only but is not recommended. This decision was made as a bug fix after identifying that releases could be tagged without verifying test health. Loops are prevented by has_unreleased_changes — after a release commit is tagged, the next run finds no unreleased changes and exits.
Source: CHANGELOG.md (0.2.2 — Bug Fixes: "Enforce tests pass before tagging a release"), AGENTS.md (Automated Release Pipeline)
ADR-005: Branch Protection + Auto-Merge Workflow
Date: 2026-06-21 (v0.2.0 unreleased)
Decision: Require branch protection on master (require pull request, require approval review, require status checks, block force pushes) and use an auto-merge workflow that programmatically enforces the APPROVE review check.
Rationale: Branch protection is the primary gate — no direct pushes to master, at least 1 APPROVE review before merge, CI quality + molecule tests must pass, and no history rewriting. The auto-merge workflow (scripts/auto_merge.py) enforces the APPROVE review check programmatically as a defense-in-depth measure. When the ready-to-merge label is added, the workflow validates PR title format, checks for APPROVE review, waits for CI, and squash-merges with title GRM-N <conventional commit message>. The post-merge workflow then marks the Vikunja task as done.
Source: CHANGELOG.md (Unreleased — Added: mandatory PR review step, auto_merge.py), AGENTS.md (Branch Protection, PR Workflow step 8)
ADR-006: Path-Based CI Filtering for Molecule Tests
Date: 2026-06-21 (v0.2.0 unreleased)
Decision: The CI workflow includes a detect-changes job that checks whether any files under ansible/ or .ansible-lint have changed. If no Ansible files are changed, molecule tests are skipped.
Rationale: This prevents non-Ansible changes (e.g., Python scripts, workflow YAML, docs) from being blocked by molecule test infrastructure flakiness. Molecule tests are only relevant when Ansible files change. The molecule-tests job depends on both quality and detect-changes, and only runs if ansible-changed == 'true'. CI triggers only on opened and synchronize PR events (not labeled) to avoid redundant runs.
Source: AGENTS.md (CI Path Filtering), .gitea/workflows/ci.yml (detect-changes job)