# Changelog ## What this builds A place where a team tells its customers what changed: a public page, a feed that readers and other tools can follow, and a mark inside the app that tells each person there is news they have not read. Read `spekkr.inputs.json` first. `authoring` says where entries are written. `in_app_badge` decides whether R5 exists and `email_subscribers` whether R6 does. Use `app_name` on the page and in the feed. ## Out of scope - A roadmap, votes and comments. - Writing the entries. The team does that. - Translating entries. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Entries - An entry has a title, a body in Markdown, a kind from `new`, `improved` and `fixed`, and the time it was published. - Its address is made from its title when it is first published and never changes after, even when the title does. - An entry is a draft until it is published. It can be given a time in the future, and appears by itself when that time comes. - The body is turned into HTML by a renderer that passes no HTML through and keeps only links that start with `http://` or `https://`, and images from this site. Accept when: changing a published entry's title leaves its address as it was, a draft appears nowhere public, and an entry set for the future appears when the clock passes its time. ### R2. The page - `/changelog` lists published entries newest first, 10 to a page. - Each entry has a page of its own, with a title, a description and a link picture for sites that show previews. - Entries show their date in words, such as "13 November 2026". Accept when: the page lists entries in order, and an entry's page has a description made from its first 160 characters of text. ### R3. The feed - `/changelog/feed.xml` is an Atom feed of the 30 newest entries. - Each entry's id in the feed never changes, whatever happens to its title, its body or the site's address. - An entry that is edited after it was published keeps its published time and gets a new updated time. - The feed answers with an `ETag`. A request that sends the same tag back gets status 304 and no body. - The page names the feed in a `link` element, so feed readers find it. Accept when: the feed passes an Atom validator, an edited entry keeps its id, and a request with the current `ETag` gets 304. ### R4. Editing after publishing - An edited entry says "Updated" with the date. - An entry can be taken down. Its address then answers 410, and it leaves the page and the feed. Accept when: a taken-down entry's address answers 410. ### R5. The badge Only if `in_app_badge` is on. - `GET /api/changelog/unseen` answers a signed-in person with the number of entries published since they last looked, and the newest 5 of them. - Opening the panel marks everything as seen up to that moment. - A new account starts with nothing unseen. People do not sign up to find years of old news waiting. - The count is at most 9. Above that the badge shows `9+`. Accept when: a person who signed up after an entry was published does not have it counted, opening the panel sets the count to zero, and an entry published afterwards makes it one. ### R6. Email Only if `email_subscribers` is on. - A form on the page takes an email address and sends a link to confirm it. Only confirmed addresses get email. - Publishing an entry sends it to every confirmed address, once, even if the entry is edited later. - Each email has a link that unsubscribes in one click, without signing in, and the headers that let a mail program offer the same. Accept when: an address that did not confirm gets nothing, an edit sends nothing, and a `POST` to the unsubscribe address removes the subscriber. ### R7. Writing entries - If `authoring` is `admin_page`: a page for administrators to write, preview, publish, set a time, edit and take down. - If `authoring` is `markdown_files`: each entry is a file in a `changelog` folder, with its title, kind and time at the top. A command reads the folder into the database, and the build fails on a file it cannot read. Accept when: an entry made the chosen way appears on the page and in the feed. ### R8. Pages - The list, an entry's page, and the panel that opens from the badge. Accept when: each page works with a keyboard alone and at a 360 pixel wide screen. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests set the clock. - A README explains how to write an entry, how to put the badge in the app, and how to run the tests.