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

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

Dependabot pull requests in sibling repositories were merged with merge commits, which `master` had to be force-pushed to undo, temporarily dropping commits. The synced rules merge pull requests without rewriting signed commits (fast-forward or merge commit), require checking a pull request's state before pushing to its branch (an already merged branch was amended), and delete fully merged branches. Repository-specific rules of the other repositories (Python / `Pipfile`, `blinkcheck`, their package conventions and CHANGELOG formats) are omitted.

Sources:
- fast-forward exception to "never push directly to `master`", PR state check, deleting merged branches, "Merging pull requests", Dependabot rebase after CI fixes and bot comments being corrupted on creation: https://github.com/fphammerle/docker-postsrsd/blob/8717f6cbdf25058c975b74889f05a1899a981975/AGENTS.md
- "`AGENTS.md` across repositories": https://github.com/fphammerle/python-manchester-code/blob/5376376879d90e4965865210f878f759703982cc/AGENTS.md (proposed in fphammerle/python-manchester-code#245)

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

+ 47 - 1
AGENTS.md

@@ -41,15 +41,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.
 
 
 ## Files synced with other repositories
 ## Files synced with other repositories
 
 
@@ -69,6 +101,9 @@
     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
   - 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.
     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.
 - 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.
@@ -77,3 +112,14 @@
 
 
 - Don't include the Claude session URL — it's private. A footer containing it may be appended
 - Don't include the Claude session URL — it's private. A footer containing it may be appended
   automatically when a PR is created; read the description back and remove it with an update.
   automatically when a PR is created; read the description back and remove it with an update.
+
+## `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).