Skip to content

Commit bc9b15e

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 5132f77 + 35e8b3a commit bc9b15e

1 file changed

Lines changed: 95 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -859,6 +859,53 @@ 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.
908+
862909
### Common Adaptation Patterns
863910

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

9531048
### Overview

0 commit comments

Comments
 (0)