Selaa lähdekoodia

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 viikko sitten
vanhempi
sitoutus
60f225af0d
1 muutettua tiedostoa jossa 47 lisäystä ja 1 poistoa
  1. 47 1
      AGENTS.md

+ 47 - 1
AGENTS.md

@@ -41,15 +41,47 @@
 - 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
 
 - 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
 
@@ -69,6 +101,9 @@
     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.
 - 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.
@@ -77,3 +112,14 @@
 
 - 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.
+
+## `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).