Skip to content

Commit 8bc4fcc

Browse files
dschoGit for Windows Build Agent
authored andcommitted
AGENTS.md: document amend!, fixup-only PRs, and direct GfW PRs (#6232)
This closes two gaps in the current `AGENTS.md` that came up while drafting #6231 and #2104: 1. The `Fixup Commits` section only covered `fixup!`. `amend!` has different semantics (replaces the target's commit message and combines diffs to produce any final state), and the "amend! whose body is the upstream commit and whose diff aligns the squashed result with that upstream commit" pattern is precisely how the first commit of #6231 anticipates the in-flight nedmalloc removal in `seen` as `e576abb9f8`. That pattern is undocumented today. 2. There is no top-level "Contributing to Git for Windows" section, only "Contributing to Upstream Git via GitGitGadget". The cross-fork `gh pr create` invocation, the conditions under which a PR is naturally a fixup/amend-only series against existing thicket commits, and the upstream-aligning `amend!` shape were all things I inferred from context rather than the guide. Add subsections that cover those gaps. Nothing in the existing text changes.
2 parents d998e37 + 35e8b3a commit 8bc4fcc

1 file changed

Lines changed: 93 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -859,6 +859,52 @@ gets squashed into.
859859

860860
Run affected tests before finalizing.
861861

862+
### `amend!` Commits
863+
864+
A `fixup!` commit keeps the target's commit message and merely combines
865+
its diff into the target. An `amend!` commit additionally **replaces**
866+
the target's commit message with its own body. Use `amend!` when the
867+
fix changes the meaning of the target sufficiently that the original
868+
subject or body is no longer accurate, or when the goal is to align a
869+
downstream commit with a specific upstream replacement.
870+
871+
The format is rigid: the first line of an `amend!` commit must be
872+
exactly `amend! <subject of target>`, followed by a blank line and then
873+
the **new** commit message that should replace the target's, starting
874+
with the new subject line:
875+
876+
```
877+
amend! mingw: use mimalloc
878+
879+
mingw: stop using nedmalloc
880+
881+
The vendored nedmalloc allocator under compat/nedmalloc/ has been
882+
unmaintained upstream...
883+
```
884+
885+
After autosquash, the resulting commit has the new subject (`mingw:
886+
stop using nedmalloc`), the new body, and a diff that is the
887+
composition of the target's diff and the `amend!`'s diff. Crafting the
888+
`amend!` diff so that the composition equals a known upstream commit's
889+
diff is the canonical way to align a downstream branch-thicket commit
890+
with an in-flight upstream replacement: when the next merging-rebase
891+
picks up the upstream commit, the byte-identical downstream commit
892+
collapses into it cleanly.
893+
894+
### PRs Composed Entirely of `fixup!` and `amend!` Commits
895+
896+
Adjusting or removing a feature that lives in the branch thicket is
897+
often best expressed as a PR that consists *only* of `fixup!` and
898+
`amend!` commits targeting the existing thicket commits. Each pair
899+
autosquashes during the next merging-rebase. Pairs whose diffs cancel
900+
exactly produce empty commits, which the rebase drops with
901+
`--empty=drop`. The end state is *as if the original commits had been
902+
edited or removed in place*, while preserving review-friendly atomic
903+
patches in the PR.
904+
905+
This is the preferred pattern for reverting a multi-commit downstream
906+
feature. Order the fixups in **reverse** of the originals so each
907+
revert applies cleanly to the worktree as you build the series.
862908
### Common Adaptation Patterns
863909

864910
**Struct field moves**: When upstream moves fields between structs, update
@@ -948,6 +994,53 @@ On Windows, `unsigned long` is 32 bits even on 64-bit systems. Use `size_t`
948994
for sizes that may exceed 4GB. Be careful with format strings: use `PRIuMAX`
949995
with a cast for `size_t` values.
950996
997+
## Contributing to Git for Windows
998+
999+
The primary contribution path for this fork is a PR against
1000+
`git-for-windows/git`'s `main` branch. The repository is laid out as a
1001+
branch thicket on top of an upstream Git base; see
1002+
[Merging-Rebases](#merging-rebases) and
1003+
[Analyzing Branch Thickets](#analyzing-branch-thickets) for the
1004+
mechanics.
1005+
1006+
### Opening a PR
1007+
1008+
Push the topic branch to a personal fork on GitHub, then:
1009+
1010+
```bash
1011+
gh pr create \
1012+
--repo git-for-windows/git \
1013+
--base main \
1014+
--head <you>:<branch> \
1015+
--title "<subject>" \
1016+
--body-file <path/to/body.md>
1017+
```
1018+
1019+
Unlike upstream contributions, the PR body is rendered as Markdown on
1020+
GitHub, not sent as email. Use the formatting that aids review:
1021+
fenced code blocks, tables, links to workflow runs.
1022+
1023+
### When the PR Adjusts the Thicket Itself
1024+
1025+
If the PR's purpose is to edit, remove, or replace existing
1026+
branch-thicket commits, the natural form is a series of `fixup!` or
1027+
`amend!` commits targeting the affected originals. See
1028+
[Fixup Commits](#fixup-commits),
1029+
[`amend!` Commits](#amend-commits), and
1030+
[PRs Composed Entirely of `fixup!` and `amend!` Commits](#prs-composed-entirely-of-fixup-and-amend-commits).
1031+
The merging-rebase that produces the next `main` autosquashes these
1032+
into the thicket; the PR exists for review of the individual
1033+
adjustments.
1034+
1035+
### When an Upstream Patch Will Replace a Thicket Commit
1036+
1037+
If an upstream patch is in flight (for instance, on `gitgitgadget/git`
1038+
in `seen` or `next`) that replaces a downstream thicket commit, an
1039+
`amend!` commit whose body is a verbatim copy of the upstream commit
1040+
message and whose diff aligns the autosquashed target with the
1041+
upstream commit's diff is the canonical pattern. The next
1042+
merging-rebase that picks up the upstream commit will recognize the
1043+
two as byte-identical and collapse them.
9511044
## Contributing to Upstream Git via GitGitGadget
9521045

9531046
### Overview

0 commit comments

Comments
 (0)