diff --git a/AGENTS.md b/AGENTS.md index ddadc7a..c670701 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,6 +38,19 @@ researching, or planning around prose that a human wrote, that's fair game. When in doubt, treat it as prose and hand it to a human. +## Blog posts are the exception — but read the style guide first + +The site's blog (`site/src/content/blog/`) is not the book. Agents may write and edit +blog posts when asked — automated posts exist precisely to communicate project updates. +Two hard requirements: + +1. **Before writing or editing any blog post, read `site/BLOG_STYLE.md` and follow + it.** The blog is written in the book's voice, and that guide defines it. Do not + write a post without loading it first. +2. **Set `automated: true` in the frontmatter of every agent-written post.** That + renders the "written by AI" disclosure banner; unlabeled machine writing is never + published. + ## Cursor Cloud specific instructions This repo is the **Pro Git** book (source in AsciiDoc). "Building" means converting diff --git a/site/BLOG_STYLE.md b/site/BLOG_STYLE.md new file mode 100644 index 0000000..42b60fc --- /dev/null +++ b/site/BLOG_STYLE.md @@ -0,0 +1,128 @@ +# Blog writing style guide + +Blog posts on the Pro Git site are written in the same voice as the book. +This guide describes that voice, derived from the book's own text, so that posts read +like they were written by the book's authors — because stylistically, they are. + +**Anyone (human or agent) writing or editing a post in `src/content/blog/` must read +this guide first and follow it.** + +Every trait below is illustrated with a real sentence from the book. + +## Voice and person + +**Address the reader as "you"; the authors are "we".** +The book talks directly to one reader and speaks as its authors, never in an +impersonal third person. + +> You're about to spend several hours of your life reading about Git. +> Let's take a minute to explain what we have in store for you. +> — *Introduction* + +**Use "Let's" to start a walkthrough or a worked example.** + +> To visualize this, let's assume that you have a directory containing three files, +> and you stage them all and commit. +> — *Branches in a Nutshell* + +**Use contractions.** +"You'll", "it's", "don't", "can't", "we're". The book is conversational, not formal. + +## Openers + +**Get to the point in the first sentence.** +Posts open with the fact, then explain. No throat-clearing, no scene-setting. + +> So, what is Git in a nutshell? +> — *What is Git?* + +**Rhetorical questions are welcome — but answer them immediately.** + +> What happens when you create a new branch? +> Well, doing so creates a new pointer for you to move around. +> — *Creating a New Branch* + +## Tone + +**Plain, concrete, and direct.** Explain *why* before *how*. + +> This is an important section to absorb, because if you understand what Git is and +> the fundamentals of how it works, then using Git effectively will probably be much +> easier for you. +> — *What is Git?* + +**No hype and no marketing language.** +Never "excited to announce", "seamless", "robust", "leverage", "delve", "game-changing". +When the book praises something, it says specifically what is good about it. + +**Dry, understated humor — sparingly.** At most one flourish per post, and only when +it lands naturally. + +> If the book spontaneously combusts at this point, you should already be pretty +> useful wielding Git in the time it takes you to go pick up another copy. +> — *Introduction* + +**Tell the reader when something matters.** + +> Pay attention now — here is the main thing to remember about Git if you want the +> rest of your learning process to go smoothly. +> — *The Three States* + +## Structure + +**Short paragraphs, one point each.** One to four sentences is typical. + +**Signpost what's coming, and end with a bridge.** +The book constantly tells you where you are going next and closes sections by pointing +forward. Posts should end the same way: where to follow along, what happens next, or +where to pitch in. + +> Let's get started. +> — *Introduction* + +**Lists are for enumerable facts; numbered lists are for step sequences.** +The book uses bullets for parallel facts (the three states) and numbers for workflows +(the basic Git workflow). Everything else is prose. + +## Sentences and punctuation + +**Mostly short and medium declarative sentences.** Vary the rhythm; don't stack three +long sentences in a row. + +**Em dashes for asides**, surrounded by spaces (the book's ` -- ` renders as an +em dash; in MDX write ` — ` directly). + +> Most operations in Git need only local files and resources to operate — generally +> no information is needed from another computer on your network. +> — *Nearly Every Operation Is Local* + +**Parentheses for quick side remarks.** + +> …you can commit happily (to your _local_ copy, remember?) until you get to a +> network connection to upload. +> — *Nearly Every Operation Is Local* + +**No exclamation points. No emoji.** + +## Formatting conventions + +- `monospace` for commands, branch names, file names, config keys: `git branch`, + `main`, `AGENTS.md`. +- _Italics_ for a new term at first use, the way the book introduces _snapshots_ + and _blobs_. Also for book titles: _Pro Git_. +- **Bold** sparingly, for the one key phrase in a paragraph — the book bolds + *stream of snapshots*, not whole sentences. +- Headings only when a post is long enough to need them; short posts are just prose. + +## Source formatting + +**One sentence per line.** +The book's AsciiDoc sources put each sentence on its own line (semantic line breaks), +which keeps diffs reviewable. Do the same in post MDX; Markdown joins the lines when +rendering. + +## Frontmatter + +- `description` is one plain sentence, in the same voice. +- Agent-written posts must set `automated: true` (see `README.md`); this renders the + "written by AI" banner and is non-negotiable. diff --git a/site/README.md b/site/README.md index f709e14..e5fa259 100644 --- a/site/README.md +++ b/site/README.md @@ -41,6 +41,9 @@ because Pagefind indexes the generated HTML. ## Writing a blog post +**Read [`BLOG_STYLE.md`](./BLOG_STYLE.md) first** — posts are written in the book's +voice, and that guide defines it. + Add an `.mdx` file to `src/content/blog/` with this frontmatter: ```mdx @@ -49,6 +52,7 @@ title: 'Post title' description: 'One-sentence summary shown in lists and search results.' date: 2026-08-02 author: 'Your Name' # optional +automated: true # optional; set when the post is generated by an AI agent --- Post body in MDX… @@ -56,6 +60,12 @@ Post body in MDX… The file name (without `.mdx`) becomes the URL: `/blog//`. +Posts with `automated: true` get a "This post was written by AI" banner at the top +(and a "Written by AI" tag in the post list) linking to `/authorship/`, the page +that explains the project's authorship policy. Human-written posts get a +"Written by a human" banner instead. **Always set `automated: true` on +agent-generated posts.** + ## Deployment `.github/workflows/deploy-site.yml` builds the site on every push to `main` and diff --git a/site/package-lock.json b/site/package-lock.json index 4d523cb..e439c3d 100644 --- a/site/package-lock.json +++ b/site/package-lock.json @@ -1,9 +1,12 @@ { - "name": "site", + "name": "progit-site", + "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { + "name": "progit-site", + "version": "1.0.0", "dependencies": { "@astrojs/mdx": "^7.0.5", "asciidoctor": "^4.0.7", diff --git a/site/src/content.config.ts b/site/src/content.config.ts index 1167140..b9c812c 100644 --- a/site/src/content.config.ts +++ b/site/src/content.config.ts @@ -8,6 +8,8 @@ const blog = defineCollection({ description: z.string(), date: z.coerce.date(), author: z.string().default('The Pro Git project'), + /** True when the post was generated by an AI agent rather than written by a human. */ + automated: z.boolean().default(false), }), }); diff --git a/site/src/content/blog/a-new-home-for-pro-git.mdx b/site/src/content/blog/a-new-home-for-pro-git.mdx index fbfc0bc..feabb08 100644 --- a/site/src/content/blog/a-new-home-for-pro-git.mdx +++ b/site/src/content/blog/a-new-home-for-pro-git.mdx @@ -2,25 +2,22 @@ title: 'A new home on the web for Pro Git' description: 'The Pro Git project now has its own site: read the book online, search it, and follow progress on the third edition.' date: 2026-08-02 +automated: true --- -The _Pro Git_ project now has a website of its own, and you are looking at it. +The _Pro Git_ project now has a website of its own, and you're looking at it. +Let's take a minute to walk through what's here. -Here is what you will find: +First, [the book itself](../../book/), readable online. +Every section is rendered straight from the AsciiDoc sources in the repository, one page per section, with a sidebar table of contents and previous/next links — so you can read it front to back or jump around as you please. -- **[The book, readable online](../../book/)** — the full text of _Pro Git_, rendered - straight from the AsciiDoc sources in the repository, one page per section with - a sidebar table of contents and previous/next navigation. -- **[Full-text search](../../search/)** — every section of the book (and every post - on this blog) is indexed, so you can jump straight to the material you need. -- **[This blog](../../blog/)** — updates and progress reports as work on the third - edition moves along. -- **[A history of the book](../../history/)** — how _Pro Git_ went from a 2009 - Apress title to one of the most widely read open source books in the world. +Second, [full-text search](../../search/) over the whole book and this blog. +If you want to know where we cover `git rebase` or the reflog, you can jump straight there instead of scanning the table of contents and hoping. -The site is rebuilt automatically from the [`progit3` repository](https://github.com/progit/progit3) -every time a change lands on `main`, so what you read here always matches the -latest state of the manuscript. +Third, [this blog](../../blog/), where we'll post updates and progress reports as work on the third edition moves along. -If you spot a problem — in the book or on the site — [issues and pull requests -are welcome](https://github.com/progit/progit3/blob/main/CONTRIBUTING.md). +And finally, [a history of the book](../../history/) — how _Pro Git_ went from a 2009 Apress title to one of the most widely read (and most widely translated) open source books in the world. + +How does the site stay current? +It's rebuilt automatically from the [`progit3` repository](https://github.com/progit/progit3) every time a change lands on `main`, so what you read here always matches the latest state of the manuscript. +If you spot a problem — in the book or on the site — [issues and pull requests are welcome](https://github.com/progit/progit3/blob/main/CONTRIBUTING.md). diff --git a/site/src/content/blog/planning-the-third-edition.mdx b/site/src/content/blog/planning-the-third-edition.mdx index 8fff599..eec5e83 100644 --- a/site/src/content/blog/planning-the-third-edition.mdx +++ b/site/src/content/blog/planning-the-third-edition.mdx @@ -1,40 +1,27 @@ --- title: 'Planning the third edition' -description: 'Git 3.0 is coming, and Pro Git is getting its first full revision since 2014. Here is what is changing and why.' +description: "Git 3.0 is coming, and Pro Git is getting its first full revision since 2014. Here's what's changing and why." date: 2026-08-02 +automated: true --- -Work has started on the third edition of _Pro Git_ — the first full revision of -the book since the second edition shipped in 2014. +Work has started on the third edition of _Pro Git_ — the first full revision of the book since the second edition shipped in 2014. +Let's take a minute to explain why now, and what's going to change. -The trigger is **Git 3.0**. After more than a decade of careful backward -compatibility, Git's maintainers have queued up a set of genuine breaking -changes, and several of them cut straight through material the book teaches -today: +So, why a third edition? +The short answer is **Git 3.0**. +After more than a decade of careful backward compatibility, Git's maintainers have queued up a set of genuine breaking changes, and several of them cut straight through material the book teaches today: -- **`main` becomes the real default branch name.** The book currently teaches - `master` first and treats `main` as an opt-in override. That flips: the - inventory counts roughly **600 renames** across the text, plus the diagrams - and screenshots that show branch names. -- **SHA-256 becomes the default object hash** for new repositories. The famous - "40-character SHA-1 string" passage — and every example hash in the book — - needs a rethink. -- **`reftable` replaces the `files` backend** as the default ref storage, which - reshapes parts of the Git Internals chapter. -- **Rust becomes a mandatory build dependency**, so "installing from source" - gets a new prerequisite. -- **New security defaults** like `safe.bareRepository` and `safe.directory` - aren't covered by the current text at all. +- **`main` becomes the real default branch name.** The book currently teaches `master` first and treats `main` as an opt-in override. That flips — and the inventory counts roughly 600 renames across the text, plus the diagrams and screenshots that show branch names. +- **SHA-256 becomes the default object hash** for new repositories. You may remember the "40-character SHA-1 string" from the book; that passage — and every example hash in the book — needs a rethink. +- **`reftable` replaces the `files` backend** as the default ref storage, which reshapes parts of the Git Internals chapter. +- **Rust becomes a mandatory build dependency**, so "installing from source" gets a new prerequisite. +- **New security defaults** like `safe.bareRepository` and `safe.directory` aren't covered by the current text at all. -Beyond the 3.0-specific work there is a decade of general staleness to clear -out: version framing ("this book was written using Git version 2"), long-stable -features still described as new, and forge screenshots from another era. +Beyond the 3.0 work, there's a decade of general staleness to clear out: the book still tells you it was written using Git version 2, describes long-stable features as new, and shows forge screenshots from another era. -The full chapter-by-chapter inventory lives in -[`REVISION_PLAN.md`](https://github.com/progit/progit3/blob/main/REVISION_PLAN.md) -in the repository, with the `master` → `main` breakdown in -[`book_master_to_main_inventory.md`](https://github.com/progit/progit3/blob/main/book_master_to_main_inventory.md). +If you want the details, the full chapter-by-chapter inventory lives in [`REVISION_PLAN.md`](https://github.com/progit/progit3/blob/main/REVISION_PLAN.md) in the repository, with the `master` → `main` breakdown in [`book_master_to_main_inventory.md`](https://github.com/progit/progit3/blob/main/book_master_to_main_inventory.md). -Progress will be posted here as chapters get revised. As always, the book is -being written in the open — follow along or pitch in at -[github.com/progit/progit3](https://github.com/progit/progit3). +We'll post progress here as chapters get revised. +As always, the book is being written in the open — follow along or pitch in at [github.com/progit/progit3](https://github.com/progit/progit3). +Let's get started. diff --git a/site/src/pages/authorship.astro b/site/src/pages/authorship.astro new file mode 100644 index 0000000..b21d49b --- /dev/null +++ b/site/src/pages/authorship.astro @@ -0,0 +1,58 @@ +--- +import Base from '../layouts/Base.astro'; +import { url } from '../lib/url'; +--- + + +
+

Humans, AI, and this project

+

Who writes what around here — and how you can always tell.

+ +
+

The book is written entirely by humans

+

+ Every sentence of Pro Git — the chapters, sections, sidebars, and captions — + is written by its human authors. That is a firm rule of this project, not a + preference: the book has named authors and a voice, and the writing is the work. + AI agents never compose, rewrite, paraphrase, or "polish" the book's prose. +

+

+ Agents do help with the mechanical work around the book: search-and-replace fixes + (like renaming master to main in examples), generating and + wiring up figures, building tooling, research, and planning. The full policy lives in + AGENTS.md + in the repository. +

+ +

Some blog posts are automated

+

+ The blog is different. Some posts there exist to communicate project updates — + progress reports, site changes, revision milestones — and those are generated by + automated agents working on the project. +

+

+ When a post was written by AI, we make that clear: it carries a + "This post was written by AI" banner at the top of the post and a + "Written by AI" tag in the post list. Posts written by a human say so + too. There is no ambiguity, and no unlabeled machine writing anywhere on this site. +

+ +

In short

+
    +
  • The book: humans, always.
    • +
  • The blog: humans or AI — always labeled at the top of the post.
    • +
+
+ +

← Back to the blog

+
+ + + diff --git a/site/src/pages/blog/[id].astro b/site/src/pages/blog/[id].astro index 26a440d..bbffce6 100644 --- a/site/src/pages/blog/[id].astro +++ b/site/src/pages/blog/[id].astro @@ -17,6 +17,21 @@ const dateFmt = new Intl.DateTimeFormat('en', { dateStyle: 'long' });
+ {post.data.automated ? ( + + + + This post was written by AI. Automated posts keep you updated on + the project — the book itself is written entirely by humans. Learn more → + + + ) : ( + + + Written by a human. How we use AI on this project → + + + )}

· {post.data.author} @@ -36,6 +51,53 @@ const dateFmt = new Intl.DateTimeFormat('en', { dateStyle: 'long' }); margin: 2.5rem 0 1.8rem; } + .authorship { + display: flex; + align-items: baseline; + gap: 0.7rem; + border-radius: 10px; + padding: 0.7rem 1rem; + margin: 0 0 1.4rem; + font-size: 0.92rem; + line-height: 1.45; + text-decoration: none; + color: var(--text); + } + + .authorship strong { + font-weight: 700; + } + + .authorship-ai { + background: var(--accent-soft); + border: 1px solid var(--accent); + } + + .authorship-ai:hover { + color: var(--accent-strong); + } + + .authorship-badge { + flex: 0 0 auto; + background: var(--accent); + color: #fff; + font-weight: 700; + font-size: 0.72rem; + letter-spacing: 0.08em; + padding: 0.15rem 0.45rem; + border-radius: 5px; + } + + .authorship-human { + background: var(--bg-raised); + border: 1px solid var(--border); + color: var(--muted); + } + + .authorship-human:hover { + color: var(--accent); + } + .post-header .meta { font-size: 0.85rem; color: var(--muted); diff --git a/site/src/pages/blog/index.astro b/site/src/pages/blog/index.astro index 83d7032..e67ddd6 100644 --- a/site/src/pages/blog/index.astro +++ b/site/src/pages/blog/index.astro @@ -20,6 +20,9 @@ const dateFmt = new Intl.DateTimeFormat('en', { dateStyle: 'long' });

  • @@ -48,6 +51,27 @@ const dateFmt = new Intl.DateTimeFormat('en', { dateStyle: 'long' }); letter-spacing: 0.06em; } + .ai-tag { + display: inline-block; + margin-left: 0.6rem; + font-size: 0.72rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.06em; + color: var(--accent-strong); + background: var(--accent-soft); + border: 1px solid var(--accent); + border-radius: 5px; + padding: 0.05rem 0.4rem; + text-decoration: none; + vertical-align: 0.08em; + } + + .ai-tag:hover { + color: #fff; + background: var(--accent); + } + .post-list h2 { margin: 0.3rem 0 0.4rem; font-size: 1.5rem;