diff --git a/site/src/content/blog/who-writes-pro-git.mdx b/site/src/content/blog/who-writes-pro-git.mdx new file mode 100644 index 0000000..4c9d0a9 --- /dev/null +++ b/site/src/content/blog/who-writes-pro-git.mdx @@ -0,0 +1,75 @@ +--- +title: 'Who writes Pro Git' +description: 'Agents help build this book, but they never write a sentence of it. Here is where the line is, why it is there, and how we enforce it.' +date: 2026-08-02 +automated: true +--- + +AI agents have a hand in building this edition of _Pro Git_ — the tooling, the figures, +the planning work — and they have not written one sentence of the book. +That's a firm rule, not a preference, and this post explains why it's there and how it works. + +## The book is written by humans + +_Pro Git_ has named authors. +When you read an explanation of the index, or a walkthrough of interactive rebase, you're +reading someone who decided what mattered and what to leave out — what order made sense, +what analogy would land, what caveat was worth the interruption. +That judgment is the work. +A book isn't a delivery mechanism for facts that could be regenerated from a prompt; +it's an argument, made in a particular voice, by people who've thought carefully about +what a reader needs to know. + +That's why the rule holds even when a machine-written change looks obviously helpful. +It's not weighed against convenience. +If a task would have an agent compose, rewrite, paraphrase, or "polish" the book's sentences, +the agent stops and hands it back to a human — every time. + +## What agents actually do + +There's plenty of work around the book that agents handle well: + +- **Mechanical search-and-replace** — renaming `master` to `main` in examples, + correcting a command flag, fixing a broken link. Substitutions, not rewrites. +- **Figures and diagrams** — generating, placing, and wiring up images. +- **Planning and inventory** — building the revision plan, the checklist in + [`progress.asc`](https://github.com/progit/progit3/blob/main/progress.asc), + scope analyses. +- **Research** — investigating Git's release history and behavior changes, + checking what a flag does across versions. Findings are reported for a human to write up. +- **Rearranging content** — moving existing sections, reordering material, fixing + cross-references — as long as the sentences aren't rewritten. +- **Tooling and this site** — the build pipeline, the Astro site, the scripts that + get the book online. + +## The test + +The rule has a one-line version: does the change put new or altered sentences in front +of the reader? +If yes, a human writes it. +If the agent is moving, replacing, illustrating, researching, or planning around prose +that a human wrote, that's fair game. +When in doubt, treat it as prose. + +## How it's enforced + +The rules live in +[`AGENTS.md`](https://github.com/progit/progit3/blob/main/AGENTS.md) at the root of +the repository — the file every agent reads before touching anything in this project. +It's checked in and public, so you can read the exact instructions the agents are given. + +Every change lands as a commit or pull request in the open, on the +[`progit/progit3`](https://github.com/progit/progit3) repository. +There's no process that can't be audited. + +The blog is the one exception: some posts exist to communicate project updates, and those +are generated by agents working on the project. +Every one of them carries a "This post was written by AI" banner — like the one at the +top of this post. +Human-written posts are labeled too. +There's no ambiguity, and no unlabeled machine writing anywhere on this site. +The [authorship page](../../authorship/) spells the full policy out if you want it in +one place. + +This post is itself an example of how the exception works. +If you want to argue with where we've drawn the line, `AGENTS.md` is one pull request away.