---
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](site.md) 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](https://sequoia.pub).

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](alerts.md).** 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.