Add an AGENTS.md file#718
Merged
Merged
Conversation
This file provides guidance for AI agents and developers working with the build-extra repository. It explains the repository's role as the artifact-definition and packaging companion to the Git for Windows fork, covering installer/portable/MinGit generators, custom Pacman packages, release-note tooling, and the reduced scope of please.sh after most release orchestration migrated to git-for-windows-automation. A dedicated "Avoiding AI Slop" section spells out the common failure modes of AI-assisted contributions (fabricated commit messages, cargo-culted code, unnecessary verbosity, Unicode punctuation, overly broad changes, hallucinated functionality) to set clear guardrails for contributors who may not review their own output carefully. Assisted-by: Claude Opus 4.6 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
…sing-dlls, pacman shadowing Document three things learned while investigating a check-for-missing-dlls CI failure caused by the Perl 5.40 upgrade: The two-layer exclusion mechanism in make-file-list.sh (package-level via PACKAGE_EXCLUDES, and file-level via grep -v patterns) and how they interact when a kept package bundles files that depend on an excluded library. How check-for-missing-dlls.sh works: it runs in all three SDK repos, calls make-file-list.sh, then verifies every DLL dependency via objdump/ldd. The pacman "shadowing" problem where the Git for Windows repository ships a higher pkgrel than upstream MSYS2, preventing a regular pacman -Syu from picking up an upstream rebuild, and the pacman -Syuu workaround. Also note that the local SDK may not be at the same revision as the CI runner, and where to look instead. Assisted-by: Claude Opus 4.6 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
The merge brought in UCRT64 support across the tooling (make-file-list, check-for-missing-dlls, please.sh, and CI), a PowerShell-based PE import parser (pe-imports.ps1) as fallback for objdump on cross-arch binaries, and the removal of the tracked git-extra.install file in favor of generating it from .install.in at build time. Update the Key Scripts table to include check-for-missing-dlls.sh and pe-imports.ps1, rewrite the check-for-missing-dlls section to describe the current two-stage approach (objdump then PowerShell fallback) and the api-ms-* skip, document the UCRT64 migration in the Architectures section with a reference to git-for-windows/git-sdk-64#117, and note that git-extra's .install is now generated.
dscho
added a commit
to git-for-windows/gfw-helper-github-app
that referenced
this pull request
Jun 23, 2026
AI-assisted contributions are a reality of open source, and that includes the maintainers themselves. Over recent months, AI has proven increasingly useful for the kind of menial, tedious work that does not require much creativity but is highly boring when done by hand: chasing down webhook delivery failures, tracing how a single slash command fans out into cross-repository workflow dispatches and check-run cascades, and adapting to GitHub API changes that quietly break the automation. This `AGENTS.md` provides enough context about the repository's architecture, conventions, and contracts that AI tools can produce reasonable results even when a human contributor fails to steer carefully. It documents the thin-Azure-Function-that-delegates-to-`git-for-windows-automation` architecture and the two contracts holding it together (workflows dispatched by file name; check-run names and summaries parsed by `cascading-runs.js`), the slash commands and how `/deploy` maps packages to architectures, the `embargoed-builds/` worktree that must _not_ be edited from `main`, and the build/test/lint commands and test-harness quirks. It mirrors `git-for-windows-automation`'s `AGENTS.md` and points back at it, since the two describe opposite ends of the same contract. Similar `AGENTS.md` files have been added to other repositories in the Git for Windows project: [git](git-for-windows/git#6198), [git-for-windows-automation](git-for-windows/git-for-windows-automation#170), [build-extra](git-for-windows/build-extra#718), [MINGW-packages](git-for-windows/MINGW-packages#194), and [MSYS2-packages](git-for-windows/MSYS2-packages#289). It is stacked on #220 on purpose, so that what it says about `/deploy` matches the code there; until that lands, the diff below also includes #220's commit.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
AI-assisted contributions are a reality of open source, and that includes the maintainers themselves. Over recent months, AI has proven increasingly useful for the kind of menial, tedious work that does not require much creativity but is highly boring when done by hand: chasing down CI failures across the installer/portable/MinGit build matrix, tracing cross-repository packaging flows, adapting file-list exclusions when upstream MSYS2 packages shuffle their contents.
This
AGENTS.mdprovides enough context about the repository's architecture, conventions, and contracts that AI tools can produce reasonable results even when a human contributor fails to steer carefully. It documents the repository structure (artifact generators, custom Pacman packages, key scripts), the two-layer exclusion mechanism inmake-file-list.shand how it interacts withcheck-for-missing-dlls.sh, theplease.shsubcommands that remain after the migration togit-for-windows-automation, platform considerations (all four architecture variants including the ongoing UCRT64 migration), coding conventions for shell/Node.js/Inno Setup/PKGBUILD files, the relationship with sibling repositories, and expectations around commit quality and AI slop avoidance.Similar
AGENTS.mdfiles have been added to other repositories in the Git for Windows project: git, git-for-windows-automation, MINGW-packages, MSYS2-packages, and git-for-windows.github.io.