Skip to content

A guide for a person about their own card, and AGENTS.md for the agents - #210

Open
DZPM wants to merge 5 commits into
work/governancefrom
work/contributor-docs
Open

DZPM wants to merge 5 commits into
work/governancefrom
work/contributor-docs

Conversation

@DZPM

@DZPM DZPM commented Oct 8, 2026

Copy link
Copy Markdown
Member

Two files for the people who work on this repository: one for a person, one for an agent. It comes off #205 because it edits the CONTRIBUTING.md that #205 adds, but it needs nothing from the board.

The contributing guide gains three sections about your own card

The guide was written for someone who wants to change the site. The people most likely to need something from it are the ones the site is about, and for them the answer is an email, not a pull request.

  • Your own card: what it is, and that an email to the association is enough to change it. No identity document asked for.
  • What is on your card: a name, a role, the events computed from the pages that list you, and nothing else unless you gave it.
  • If you would rather not appear: how to have it removed, and what removal can and cannot do on a public repository. The card goes from the site and from the build, and we ask the search engines and the Internet Archive to drop their copies; the Git history keeps it, and so does anyone who already copied it. If that is not acceptable, tell us before we publish, because we would rather not publish a card than publish one we cannot withdraw.

That last paragraph is the one worth reading twice. It is the same reasoning LICENSING.md gives in #205 for why the photographs carry no licence.

AGENTS.md

A file for AI coding agents, beside the contributing guide for people. What an agent gets wrong that a human would not, and what this repository does differently from a stock Hugo site: the pinned binary at bin/hugo and why not to pip install hugo, the TOML key that lands inside the last table and silently does nothing, merge.ff = only, unsafe = true in the Goldmark renderer and the two content files that still carry raw HTML, images under assets/ rather than static/, and master being the built site rather than a source branch.

Both drafts had gone stale, and were corrected against the tree

The contributing text was written for the Archive, where every person was going to have a page of their own at a URL. They do not: config.toml cascades render = "never" over content/people, so a person file builds no page. It also named a short_bio field that no longer exists, a content/talks/ section that was never created, and a privacy policy at a path the site does not serve.

AGENTS.md had four facts that no longer held. Each was checked before committing:

It said It is
A clean build gives 310 HTML pages 317: 261 from Hugo and 56 copied from static/archives/. The line now says to recount rather than trust it
resources/_gen/ is tracked, so a build dirties the tree It and docs/ are gitignored. A dirty tree there means a branch from before that change
Two content files need unsafe raw HTML True, and now it also says what guards them: bin/check-html-safety and bin/check-rendered, on every pull request
bin/serve runs on :1313 It takes no port and uses Hugo's own default

The table of paths gains data/, and a table of the three checks a pull request has to pass.

DZPM added 2 commits October 8, 2026 11:15
The contributing guide was written for someone who wants to change the site.
The people most likely to need something from it are the ones the site is
about, and for them the answer is an email, not a pull request.

Three sections say so. What is on a card, which is a name, a role, the
events computed from the pages that list the person, and nothing else unless
they gave it. How to change it, which is an email to the association or the
pencil icon on GitHub, with no identity document asked for. And how to have
it removed, with what removal can and cannot do on a public repository: the
card goes from the site and from the build, and we ask the search engines
and the Internet Archive to drop their copies, but the Git history keeps it
and so does anyone who already copied it. Whoever is not happy with that
should tell us before we publish, and we would rather not publish a card
than publish one we cannot withdraw.

The text comes from a draft written for the Archive, where every person was
going to have a page of their own at a URL. They do not: config.toml
cascades render = "never" over content/people, so a person file builds no
page. The draft also named a short_bio field that no longer exists, a
content/talks section that was never created, and a privacy policy at a path
the site does not serve. All of that is rewritten to the site as it is.
A file for AI coding agents, beside the contributing guide for people. It
holds what an agent gets wrong that a human would not, and what this
repository does differently from a stock Hugo site: the pinned binary at
bin/hugo and why not to pip install hugo, the TOML key that lands inside the
last table and silently does nothing, merge.ff = only, unsafe = true in the
Goldmark renderer and the two content files that still carry raw HTML,
images under assets rather than static, and master being the built site
rather than a source branch.

The draft was written on 2026-10-03 and four of its facts had gone stale,
so each one was checked against the tree before this commit:

- The page count was 310. A clean build gives 317: 261 from Hugo and 56
  copied from static/archives. The line now says to recount rather than
  trust it.
- It said resources/_gen is tracked in Git and that a build dirties the
  tree. Both it and docs/ are gitignored now, so the line says what a dirty
  tree there actually means: a branch from before that change.
- It named the two files that need unsafe raw HTML without saying what
  guards them. bin/check-html-safety and bin/check-rendered do, on every
  pull request, and both are now in the file.
- bin/serve takes no port: it runs Hugo's own default.

The table of paths gains data/ and a table of the three checks, which are
what a pull request has to pass.
@DZPM DZPM self-assigned this Oct 8, 2026
@DZPM
DZPM requested review from ber2, mesejo and mrswats October 8, 2026 09:31

@ber2 ber2 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excellent stuff, @DZPM

@DZPM
DZPM requested a review from a team as a code owner October 8, 2026 17:54
DZPM added 2 commits October 8, 2026 20:04
It said 317, which was true when the file was written and stopped being
true the moment #202 merged: that pull request stopped publishing the 206
person and sponsor pages, so a clean build is 109 pages now, 53 from Hugo
and 56 copied from static/archives.

The line already told a reader to recount rather than trust it. It now also
says what happened, because a figure that went stale in a day is the best
argument for recounting.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants