Add an AGENTS.md to orient agents and developers#221
Merged
Conversation
Git for Windows' SDK is migrating from the MINGW64 to the UCRT64 environment, so the packages we ship need UCRT64 variants from now on. The build-and-deploy workflow already learned about the `ucrt64` pseudo architecture, which means `/deploy` can finally request those builds, but I do not want to do that by leaning on the workflow's combined run: with no explicit architecture it builds mingw32, mingw64 and ucrt64 one after another in a single job, and packages such as mingw-w64-openssl and mingw-w64-curl already take long enough that serializing a third environment on top would hurt. Dispatching one run per architecture lets them build in parallel on separate runners instead, turning the wall-clock from the sum of the three into the slowest of them. So for a regular MINGW package `/deploy` now starts individual `i686`, `x86_64` and `ucrt64` runs alongside the existing `arm64` one, rather than a single combined run plus `arm64`. git-extra is a regular MINGW package in this sense and gets the same treatment; its `.src.tar.gz` is still built exactly once, in the `x86_64` run. The set of packages that get built and deployed is unchanged; only the granularity of the runs is. Three packages stay on a single combined run: mingw-w64-git-credential- manager, mingw-w64-git-lfs and mingw-w64-wintoast are not built per architecture by us at all, but cross-compiled via Visual Studio or downloaded as pre-built artifacts for every architecture (including clangarm64) at once. mingw-w64-llvm keeps getting only the `arm64` run via `/deploy`, as before. To express that, the predicate that used to be called `needsSeparateARM64Build` is replaced by its inverse, `buildsAllArchitecturesInOneRun`, which positively names exactly those three exceptional packages. I first tried merely renaming it to `isMINGWPackage`, but that does not fit: the three exceptions are themselves MINGW packages, so a predicate that excludes them cannot honestly claim to answer "is this a MINGW package". Identifying the special cases directly keeps both the predicate and the resulting three-way dispatch (MSYS, combined, per-architecture) self-explanatory. The UCRT64 support in the build-and-deploy workflow landed in git-for-windows/git-for-windows-automation#178, and the overall SDK migration is tracked in git-for-windows/git-sdk-64#117. Assisted-by: Opus 4.8 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Every sibling repository in the Git for Windows constellation that an AI agent is likely to touch (git-for-windows-automation, build-extra, MINGW-packages, MSYS2-packages) ships an AGENTS.md, but this one did not, even though it is one of the harder repositories to reason about from the source alone: it is an Azure Function that does little itself and instead dispatches workflows elsewhere by filename and communicates back through check-run names and summaries. Those cross-repository couplings are invisible until something breaks. This file captures the parts that bit me, or would have, while extending the `/deploy` command this session: that workflows are dispatched by filename (so renames must be coordinated with git-for-windows-automation), that check-run names and summaries are a parsing contract consumed by cascading-runs.js, that `embargoed-builds/` is a separate long-lived worktree which must not be edited as part of `main` changes, and that `npm test` also picks up that worktree's suites unless scoped to `npx jest __tests__/`. It deliberately mirrors the structure of git-for-windows-automation's AGENTS.md and points back at it, since the two describe opposite ends of the same contract. It is stacked on top of the per-architecture `/deploy` change so that its description of how `/deploy` maps packages to architectures (the `buildsAllArchitecturesInOneRun` predicate, the separate i686/x86_64/ucrt64 runs) stays consistent with the code it documents. Assisted-by: Opus 4.8 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
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 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.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 thin-Azure-Function-that-delegates-to-git-for-windows-automationarchitecture and the two contracts holding it together (workflows dispatched by file name; check-run names and summaries parsed bycascading-runs.js), the slash commands and how/deploymaps packages to architectures, theembargoed-builds/worktree that must not be edited frommain, and the build/test/lint commands and test-harness quirks. It mirrorsgit-for-windows-automation'sAGENTS.mdand points back at it, since the two describe opposite ends of the same contract.Similar
AGENTS.mdfiles have been added to other repositories in the Git for Windows project: git, git-for-windows-automation, build-extra, MINGW-packages, and MSYS2-packages.It is stacked on #220 on purpose, so that what it says about
/deploymatches the code there; until that lands, the diff below also includes #220's commit.