id: updates title: The project says what it has done, where the network can read it status: open crates: [] dependsOn: [site] exitCriterion: > A release note written in site/ is live on did.bot and carries a site.standard.document record, /.well-known/site.standard.publication proves who owns the publication, and a client that has never heard of this project renders the feed from the record alone. #

updates #

site is what a stranger reads to find out what this project is. It has no way to say what changed. This epic gives it an updates section — release notes and announcements, prerendered from markdown like the rest of the site — and publishes each post to ATProto as a site.standard.document record with sequoia.

These are the software project's updates: what shipped, what broke, what an operator should know before upgrading. They are a property of the project, and they live where the project's public face lives.

Publishing them as records rather than only as HTML is what makes them readable by something other than a browser pointed at did.bot: a feed reader, an atproto client, an unfurled link. headquarters at lance.blue already does exactly this and is the framework being carried across. Where the two agree, this file points there rather than restating it.

What this is not #

• Not a demonstration that the server works. It is tempting to publish the project's updates into a repository the project's own server hosts, because running that server is what this repository is for. It is the wrong instinct twice over. It makes the project unable to announce an outage during one — the post about the server being down would need the server — and it couples a communications channel to a deployment for no benefit the reader can see. If dogfooding is worth doing it is a separate decision with its own reasoning, not a property this epic assumes.
• Not alerts. That is machine-written, addressed to an operator, and must not be edited after the fact. This is edited prose addressed to anybody. The two share nothing but a verb.

Whose repository #

• Decide, and prefer the boring answer. The publication belongs to whichever account is the project's public voice. headquarters writes into an ordinary atproto account over an app password, which needs no infrastructure of this project's own and keeps the update feed working on a day the deployment is not. That is the default this epic should have to argue its way out of, not the fallback.
• Whatever is chosen, it is permanent in practice. A publication record is referenced by every document under it and by the well-known file that proves ownership; moving it later means reissuing both.

What the framework already establishes #

Carried from the publishing epic and web/scripts/ in headquarters' own repository, which are worth reading before building any of this:

• Ownership is proved by a well-known file. /.well-known/site.standard.publication carries the publication's at:// URI, and sequoia.json carries the same. Both are written once and committed; nothing rewrites them.
• The live check compares the canonical link, not the status code. A post is refused if the site is not already serving it — and a missing page on a static site comes back as the app's own index.html with a 200, so a status check passes on a page that does not exist. This is the kind of detail that looks like a nicety until it silently publishes a record pointing at nothing.
• A new post currently takes two deploys, because publishing writes an atUri back into the post's frontmatter and the link tag renders from it. Commit, deploy, publish, commit the atUri, deploy again. Work out whether that is inherited here or avoidable; it is a papercut that will be paid on every post.
• The reference implementation is not proven. headquarters' own epic records that publish.sh has never run against the real sequoia CLI — the records so far were made with the CLI by hand — so its parsing of sequoia publish --dry-run --verbose is untested. Inheriting the design is sensible; inheriting confidence in it is not. This epic is not met until a real, non-dry-run publish has happened.

The dependency worth naming #

• A CLI in the publish path. sequoia is a tool this project does not build, invoked by a script that parses its output. Say what happens when it is absent, and what happens when its output format moves — the failure to avoid is a publish that reports success having written nothing.

Done #

Nothing closed yet.