Просмотр исходного кода

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

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.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fabian Peter Hammerle 3 дней назад
Родитель
Сommit
2f3ef563b6
1 измененных файлов с 60 добавлено и 3 удалено
  1. 60 3
      AGENTS.md

+ 60 - 3
AGENTS.md

@@ -13,6 +13,7 @@
 
 
 - Attribution line: `Co-Authored-By: Claude <model name> <noreply@anthropic.com>` — always include the model name,
 - Attribution line: `Co-Authored-By: Claude <model name> <noreply@anthropic.com>` — always include the model name,
   e.g. `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`
   e.g. `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`
+  (see https://web.archive.org/web/20261016172400/https://docs.github.com/en/pull-requests/how-tos/commit-changes/creating-a-commit-with-multiple-authors)
 - Do **not** include a `Claude-Session:` line — the session URL is private.
 - Do **not** include a `Claude-Session:` line — the session URL is private.
 - Explain **why**, not what — don't restate in prose what's already obvious from `git diff` of
 - Explain **why**, not what — don't restate in prose what's already obvious from `git diff` of
   the commit (e.g. "add a notice to the README", "update section X").
   the commit (e.g. "add a notice to the README", "update section X").
@@ -23,6 +24,8 @@
 ## CHANGELOG
 ## CHANGELOG
 
 
 - Only document **user-facing** changes (features, bug fixes, removed support).
 - Only document **user-facing** changes (features, bug fixes, removed support).
+- CI / build tooling changes (e.g. GitHub Actions workflows, `dependabot.yml`) are not
+  user-facing → no entry needed.
 - Test tooling changes (e.g. `[dev-packages]` in `Pipfile`, `Pipfile.lock`) are not user-facing →
 - Test tooling changes (e.g. `[dev-packages]` in `Pipfile`, `Pipfile.lock`) are not user-facing →
   no entry needed.
   no entry needed.
 - Changes to the container image (`Dockerfile`, base image, `docker-apparmor-profile`,
 - Changes to the container image (`Dockerfile`, base image, `docker-apparmor-profile`,
@@ -41,15 +44,47 @@
 - One commit per PR; amend rather than adding new commits.
 - One commit per PR; amend rather than adding new commits.
 - Force-push with `--force-with-lease` on feature branches.
 - Force-push with `--force-with-lease` on feature branches.
 - **Never force-push to `master`.**
 - **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
 - **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
   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`)
   reflects what merged. For a follow-up change, create a **new** branch (from current `master`)
   and a **new** PR instead.
   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
 ## CI failures
 
 
 - Fix CI failures automatically, iterating until all checks are green — no need to ask first.
 - Fix CI failures automatically, iterating until all checks are green — no need to ask first.
+- After a fix for a failing build is merged into `master`, **automatically** comment the
+  Dependabot rebase command on each of Dependabot's open pull requests (without being asked), so
+  their checks re-run on top of the fix instead of staying red. Follow the mandatory steps in
+  "GitHub comments that @-mention a bot" below.
 
 
 ## Supported Python versions
 ## Supported Python versions
 
 
@@ -75,8 +110,19 @@
   - Post such comments **one at a time**, never several in parallel.
   - 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
   - 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.
     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 (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
 - 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
   bot commands literally there (describe them instead, e.g. "the Dependabot rebase command"), and
   read every PR description back after creating or updating it.
   read every PR description back after creating or updating it.
@@ -100,3 +146,14 @@
   resolution, put them in `[packages]`, not `[dev-packages]`.
   resolution, put them in `[packages]`, not `[dev-packages]`.
 - `[packages]` (`default` in `Pipfile.lock`) is installed in the container image too, not only in the
 - `[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").
   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).