Browse Source

AGENTS.md: sync with instructions of other repositories (#353)

Creating and editing the Dependabot rebase comment both produced a corrupted body on fphammerle/docker-postfix#158, so bot commands now fall back to other automatic approaches and, as a last resort, to asking the user with the exact link to post at. Other shared rules that were missing here (merging pull requests without rewriting signed commits, PR state check before pushing, deleting merged branches, Dependabot rebase after CI fixes, `AGENTS.md` across repositories, CI / build tooling not being user-facing) are synced as well; repository-specific rules are kept unchanged.

The rule against justifying version updates with pins no longer being installable now names `Dockerfile` pins explicitly, since that's the only kind of pin it applies to.

Source: https://github.com/fphammerle/docker-postfix/blob/ecc55138f443946e20d3abe0d00b86ef762a7dfb/AGENTS.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fabian Peter Hammerle 2 days ago
parent
commit
a29c99f246
1 changed files with 57 additions and 10 deletions
  1. 57 10
      AGENTS.md

+ 57 - 10
AGENTS.md

@@ -20,10 +20,10 @@
 - When content is copied or adapted from another repository, reference the sources with full
   permanent URLs (commit hash + path), e.g. `https://github.com/<owner>/<repo>/blob/<sha>/<path>`.
 - Don't hard-wrap long lines in commit message bodies — write each paragraph / list item on a single line; git log viewers wrap them automatically.
-- Never justify a version update with the old pinned version no longer being installable or the
-  build failing because of it (e.g. "so the pinned version can no longer be installed") — pins are
-  intentional and breaking when upstream moves on is their whole point. Keep versions pinned; this
-  applies to PR descriptions as well.
+- Never justify a version update of a pin in `Dockerfile` (e.g. `BASE_IMAGE`) with the old pinned
+  version no longer being installable or the build failing because of it (e.g. "so the pinned
+  version can no longer be installed") — pins are intentional and breaking when upstream moves on
+  is their whole point. Keep the version pinned; this applies to PR descriptions as well.
 
 ## CHANGELOG
 
@@ -45,11 +45,39 @@
 - One commit per PR; amend rather than adding new commits.
 - Force-push with `--force-with-lease` on feature branches.
 - **Never force-push to `master`.**
-- **Always open a pull request — never push directly to `master`.**
+- **Always open a pull request — never push directly to `master`** (the only exception is
+  fast-forwarding `master` to a pull request's head commit, see "Merging pull requests").
 - **Never amend or force-push a branch whose PR is already merged or closed** — that rewrites
   history that's already landed (or been reviewed) and leaves a dangling branch that no longer
   reflects what merged. For a follow-up change, create a **new** branch (from current `master`)
   and a **new** PR instead.
+  - This has happened despite this rule, so before **every** amend / push to an existing branch,
+    first fetch its PR's current state from GitHub — pull requests may have been merged since you
+    last looked.
+- After a branch has been **fully** merged into `master`, delete it (on GitHub and locally). If
+  only a subset of its commits was merged, keep it and rebase the remaining commits onto `master`
+  instead (`git rebase --onto origin/master <last merged commit>`).
+
+## Merging pull requests
+
+- Keep existing commit signatures: never rewrite commits when merging — no GitHub squash or rebase
+  merge, no cherry-picking or re-creating commits locally. Rewriting replaces signed commits (e.g.
+  Dependabot's) with new, unsigned or differently signed ones.
+- Pull requests / branches with a **single commit**, or whose changes should be squashed into a
+  single commit: **fast-forward** `master` to the branch's head commit, so that exact commit lands
+  on `master`.
+  - Squashing belongs on the branch, done by its author — squashing someone else's signed commits
+    yourself would drop their signatures.
+  - The head commit's parent must be the current `master` tip. If it isn't, have the branch
+    rebased by its author (for Dependabot: the rebase command, see "GitHub comments that
+    @-mention a bot").
+  - All checks must have passed on **that exact head commit** — a push to `master` doesn't wait
+    for them the way GitHub's merge button does.
+  - Then push the head commit: `git push origin <head-sha>:master` (no force) — GitHub marks the
+    pull request as merged.
+- Pull requests / branches with **multiple commits that should stay separate**: create a merge
+  commit (GitHub merge method `merge`).
+- Never call GitHub's merge API without an explicit merge method, and never use `squash` or `rebase`.
 
 ## CI failures
 
@@ -83,11 +111,19 @@
   - Post such comments **one at a time**, never several in parallel.
   - Immediately after posting, read the comment back from GitHub and compare it character by
     character with the intended text. Only then post the next one.
-  - If the body is wrong, edit the comment to the exact intended text (Dependabot does act on
-    edited comments) and read it back again — don't leave a broken command posted.
-  - Creating the comment has corrupted the body **every time** so far, while editing it to the
-    same text came through intact — so never consider a bot command posted after the create
-    call alone; the read-back and (almost always needed) edit are part of posting it.
+  - Creating the comment has corrupted the body **every time** so far (stray `·` inside the
+    command, plus an appended "Generated by Claude Code" footer), so never consider a bot command
+    posted after the create call alone.
+  - If the body is wrong, edit the comment **once** to the exact intended text (Dependabot does act
+    on edited comments) and read it back again. Editing used to fix the body, but has also come
+    back corrupted (twice in a row on fphammerle/docker-postfix#158).
+  - If the edited body is still wrong, don't keep re-editing the same way. First re-check whether
+    another **automatic** approach is available to fix the comment or re-post it (e.g. another
+    tool or API that reaches GitHub without the corruption), and apply it, again with read-back.
+  - Only if that fails too, ask the user to post the command, naming the **exact link** to post it
+    at (the pull request URL, e.g. `https://github.com/<owner>/<repo>/pull/<number>`) and the exact
+    command text; mention the broken comment's link so it can be deleted. Continue once the bot has
+    acted on it.
 - The same corruption also hits `@mentions` in PR descriptions and other GitHub text. Don't quote
   bot commands literally there (describe them instead, e.g. "the Dependabot rebase command"), and
   read every PR description back after creating or updating it.
@@ -111,3 +147,14 @@
   resolution, put them in `[packages]`, not `[dev-packages]`.
 - `[packages]` (`default` in `Pipfile.lock`) is installed in the container image too, not only in the
   test environment — don't describe changes to it as test-only (e.g. "relock test environment").
+
+## `AGENTS.md` across repositories
+
+- The `AGENTS.md` files of the owner's repositories share most of their rules. Find them all with
+  a GitHub code search for `user:fphammerle filename:AGENTS.md`.
+- Creating an `AGENTS.md` for a repository: base it on **all** of them, not just one. Start from
+  the closest sibling, keep only the rules that fit the particular repository (e.g. no Python /
+  `Pipfile` rules for a `Dockerfile`-only repository, no rules on `Dockerfile` version pins for a
+  repository without a `Dockerfile`), and adapt repository-specific examples
+  (e.g. package names, commit subject conventions from `git log`). In the commit message, reference
+  the individual source each part was based on with full permanent URLs (commit hash + path).