Skip to content

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

Open
jackspiering wants to merge 3 commits into
mainfrom
docs-contributor-guidance
Open

jackspiering wants to merge 3 commits into
mainfrom
docs-contributor-guidance

Conversation

@jackspiering

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 pinned rumdl version;
    • 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant