Skip to content

Docs: update AGENTS, CONTRIBUTING, and the templates - #372

Merged
crypt0rr merged 7 commits into
mainfrom
docs-contributor-guidance
Oct 13, 2026
Merged

crypt0rr merged 7 commits into
mainfrom
docs-contributor-guidance

Conversation

@jackspiering

@jackspiering jackspiering commented Oct 10, 2026 •

Copy link
Copy Markdown
Collaborator

Description

Brings AGENTS.md, CONTRIBUTING.md, the pull request template and the service template in line with what #367 and #368 changed.

  • AGENTS.md is rewritten: where the rules live, which files change together, how to handle secrets and runtime data, validation and lint commands, and the PR title format.
  • CONTRIBUTING.md:
    • documents the required-secret pattern (${VAR:?...} plus a # Required: comment);
    • gives a validation command that works for stacks with required secrets;
    • adds the whole-repository lint with the rumdl version that linting.yml pins, read from that file, with uvx or the release binary;
    • says that the rules apply to new stacks and to the parts of an existing stack that a change touches;
    • tells contributors to start test stacks from a copy outside the repository;
    • says when an "Upgrading" section is required;
    • states the PR title format;
    • stops claiming that Serve cannot read SERVICEPORT, and loosens the naming rules to point at "Deviations from the standard setup";
    • keeps one copy of the health-check ladder.
  • Pull request template: replaces the label checkbox (contributors cannot set labels) with items for Compose validation, lint and credentials.
  • Service template: comments out PUID/PGID with an explanation (TZ stays), puts .env comments on their own line, replaces #COMPOSE_PROJECT_NAME with a note on running a second copy, and removes #version=1.1. The auth key link is console.tailscale.com, as in Tailscale's docs.

Related Issues

  • None.

Verification

  • The template validates with SERVICE=dummy IMAGE_URL=dummy docker compose config --quiet, before and after.
  • The validation command was run (with the dummy values it generates written out) for netbox, tandoor, copyparty and uptime-kuma. The generator pipeline was checked on tandoor.
  • X= # note yields # note, and X=value # note yields value, checked with a scratch Compose project.
  • rumdl check --config .markdownlint.yml . (0.2.78) and git diff --check origin/main are clean.
  • Not run: any stack through the Tailnet. These are documentation and template comment changes.

Checklist

  • I have performed a self-review of my code and followed the templates structure.
  • I have added verification that the stack works as expected.
  • I have updated necessary documentation (e.g. frontpage README.md ).
  • I have selected the correct label(s) for this PR.

Additional Context

From an external review of the repository (sections 1 and 3.4).

  • The docs say CI fails on "variable is not set" warnings. That is true once the CI PR is merged.
  • The alphabetical-order rule assumes the README PR (re-sorted tables) is merged.
  • The auth key link still differs in the root README and 35 service .env files. They are not changed here, because every .env edit makes git pull stop for existing users.

CONTRIBUTING.md now points to the template comments for the database case. Two rules from the removed paragraph were missing there: a database image's own HEALTHCHECK comes first, and a service that depends on the database waits with condition: service_healthy.
The documented validation command fails on the template, because SERVICE and IMAGE_URL are empty there. AGENTS.md and CONTRIBUTING.md now give the command with dummy values, as CI uses.
@jackspiering
jackspiering requested a review from crypt0rr October 10, 2026 13:06
CONTRIBUTING.md asks for an explicit image tag, but the example in the template had none and misspelled the image name.
…version number

The rules apply to new stacks and to the parts of an existing stack that a change touches, so existing stacks that differ are not violations to fix at once. The lint instructions read the rumdl version from linting.yml and offer the release binary next to uvx, so a version bump needs no doc edit.
git diff --check origin/main compares with the wrong branch in a fork. A tracked file inside a data folder needs its own exception in .gitignore, because the folder rules ignore it.
@jackspiering jackspiering added the documentation Improvements or additions to documentation label Oct 13, 2026
@crypt0rr
crypt0rr merged commit 81bdc70 into main Oct 13, 2026
4 checks passed
@crypt0rr
crypt0rr deleted the docs-contributor-guidance branch October 13, 2026 10:47
@jackspiering jackspiering mentioned this pull request Oct 13, 2026
2 of 4 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants