From fe3ab8a9f120e2ec528503785e191f25a7254b55 Mon Sep 17 00:00:00 2001 From: James Manuel Date: Thu, 23 Jul 2026 15:20:49 +0200 Subject: [PATCH] docs: add agent instructions for commit hygiene Codifies three things this session's PR reviews (#79, #83) ran into repeatedly: branches based on a stale main, unsigned commits failing DCO, and hand-committed build assets. AGENTS.md holds the actual content; CLAUDE.md imports it since Claude Code doesn't read AGENTS.md natively. Signed-off-by: James Manuel --- AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 46 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bbfdb9e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,45 @@ +# Agent instructions + +Instructions for AI coding agents (Claude Code and others) working in this repo. +Human contributors: see `README.md`. + +## Before starting work + +Sync with `origin/main` before branching and again before opening a PR. Branch +from a stale base and CI's `npm-build` "Check build changes" job, DCO check, or +plain merge conflicts will fail for reasons unrelated to your change — and a +refactor may have moved the code you're about to edit somewhere else entirely. + +```bash +git fetch origin +git checkout -b origin/main +``` + +If you've been working for a while, `git fetch origin && git log --oneline +HEAD..origin/main` before pushing — rebase if `main` has moved. + +## Commit atomically + +One concern per commit: a functional change, a cleanup, and a docs update are +three commits, not one. Do not bundle an unrelated fix into a feature commit +because it happened to be nearby. A reviewer (human or bot) diffing a single +concern can actually verify it; a "fix + refactor + docs" commit can't be +reviewed, only trusted. + +This applies to AI-authored changes as much as human ones. Confident, +well-commented AI output still needs to be split and verified per concern — +a flawless-looking helper and a real bug can come from the same commit. + +## Sign off every commit + +`git commit -s`. DCO is enforced by CI; a missing `Signed-off-by:` trailer +fails the PR regardless of how correct the change is. + +## Never hand-commit build artifacts + +Do not stage or commit changes under `js/` or `css/` — see `README.md` +("Committing changes") for the full flow. Source only; the `nextcloud-command` +bot recompiles and commits assets via `/compile` on the PR. `.githooks/pre-commit` +blocks this locally as a backstop, but don't rely on the hook catching it — +run `npm run build` for local testing, then `git restore --staged js css` +(or don't stage them in the first place) before committing. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md