74 lines
5.6 KiB
Markdown
74 lines
5.6 KiB
Markdown
# Release notes format
|
|
|
|
Name: `vX.Y.Z-beta - Short theme` (theme is 2 to 6 words, sentence case).
|
|
Tag: `vX.Y.Z-beta`, always with the `v`.
|
|
|
|
Body, in this order. Omit a section only when it would be empty, except Upgrading, which is always present.
|
|
|
|
1. Intro: one or two plain sentences on what the release is about. No heading.
|
|
2. `## New`: user-visible features. Group with a bold title line (`**Group name**`) followed by bullets.
|
|
3. `## Improvements and fixes`: flat bullets.
|
|
4. `## API`: one bullet per endpoint change, `METHOD /v1/path` in backticks, then behaviour and status codes. Prefix breaking or shape changes with "Changed:".
|
|
5. `## Under the hood`: dependencies, tests, docs, architecture. Only when relevant to contributors.
|
|
6. `## Upgrading`: binary replacement, schema/migration changes, new env vars, behaviour changes for existing installs.
|
|
7. `## Known limitations`: only when there are real ones.
|
|
|
|
Rules: bullets are full sentences ending with a period; user-facing wording, no commit prefixes; sentence-case headings; no horizontal rules, no metadata block, no "Pre-1.0" boilerplate (the prerelease flag says it); every release ships all 6 binaries from `task release`.
|
|
|
|
## Next release (draft)
|
|
|
|
Articles and sites now store the data a website needs for search and sharing, and every article gets an address that is unique on its site.
|
|
|
|
### New
|
|
|
|
**Article SEO fields**
|
|
|
|
- An article has a slug, an excerpt, a search title and description, a cover image with its alt text, a social title, description and image, a canonical address, a noindex flag and a list of dismissed suggestions.
|
|
- The slug is generated from the title, is unique per site and can be changed at any time; an empty slug regenerates it from the title.
|
|
- A site has a site name, a title template and a default description.
|
|
|
|
### API
|
|
|
|
- `PATCH /v1/article/{id}` also takes the SEO fields. `cover_image_id` and `social_image_id` accept `null`. A slug already used on the target site answers `409` `slug_taken` with the header `X-Slug-Suggestion` holding the first free slug.
|
|
- `GET /v1/article/{id}`, `POST /v1/article/`, `PATCH /v1/article/{id}`, `PATCH /v1/article/{id}/publish` and `PATCH /v1/article/{id}/unpublish` return the twelve SEO fields; the items of `GET /v1/article/` return `slug` and `excerpt`.
|
|
- `POST /v1/site/` and `PATCH /v1/site/{id}` take `site_name`, `title_template` and `default_description`; a template without `%title%` is `400` `invalid_title_template`.
|
|
- Changed: `GET /v1/media/{id}/usage` stays an array, and every item gains `type` and `fields` without losing `id`, `title` and `published`. Authors and sites that use the image are now listed, without a `published` key.
|
|
- Changed: a cover image, a social image, an author avatar and a site default social image all count in `used_in` and in the `unused` filter. Deleting an image clears the covers and social images that use it, and merging or purging repoints them.
|
|
|
|
### New: SEO output
|
|
|
|
- `GET /v1/article/{id}/seo` returns the resolved search and sharing data of an article (title with the site template, description, canonical address, robots, Open Graph, Twitter, image, authors and ready JSON-LD), so a frontend can render its meta tags without reimplementing the fallback chain. Drafts answer verified callers only.
|
|
- `POST /v1/article/{id}/seo/check` evaluates an article without saving, with optional overrides, and reports the suggestions, the status and whether the slug is free.
|
|
- `GET /v1/article/` items carry `seo_status` and `seo_suggestions`, and the new `seo` parameter filters on the status.
|
|
- `GET /v1/site/{key}/sitemap` lists the published URLs of a site, paged, with the total in `X-Total-Count`, which is now exposed to browsers through CORS.
|
|
|
|
### Upgrading
|
|
|
|
- The first start after the upgrade adds the new columns, gives every existing article a slug generated from its title (in id order within each site, with `-2`, `-3` on conflicts) and creates the unique `(site_id, slug)` index. Nothing else changes, and a second start changes nothing.
|
|
- A deleted article now frees its slug.
|
|
|
|
## Published releases
|
|
|
|
Each body lives in `docs/releases/<tag>.md`. Publish with `tea releases create --tag <tag> --title "<tag> - <theme>" --note-file docs/releases/<tag>.md --prerelease --asset <file>` after `task release`, with one `--asset` per file: the six binaries, `bin/checksums.txt` and `bin/checksums.txt.sig`. `task release` produces all eight and fails before building when the signing key is missing or wrong (see [deployment.md](deployment.md#release-signing-key-maintainers-once)). Never publish a release without the two checksum files.
|
|
|
|
| Tag | Theme |
|
|
| --- | --- |
|
|
| `2.0.0-beta` (legacy tag without the `v`, kept as is) | Vue 3 SPA and domain-driven backend |
|
|
| `v2.1.0-beta` | Image upload in the editor |
|
|
| `v2.2.0-beta` | Image crop, image removal & reset screens |
|
|
| `v2.3.0-beta` | Multi-user invitations, display names & profile page |
|
|
| `v2.4.0-beta` | Owner role, invite management & Settings page |
|
|
| `v2.5.0-beta` | Media library & image picker |
|
|
| `v2.6.0-beta` | Signed updates and browser restart |
|
|
| `v2.6.2-beta` | English and French interface |
|
|
| `v2.7.0-beta` | Markdown and block article bodies |
|
|
| `v2.8.0-beta` | API keys and API reference |
|
|
| `v2.8.1-beta` | Docker deployment |
|
|
| `v2.8.2-beta` | Security headers and clearer log in errors |
|
|
| `v2.8.3-beta` | Security policy fixes for the web app |
|
|
| `v2.9.0-beta` | Media duplicate purge |
|
|
| `v3.0.0-beta` | Activity log, more databases and S3 storage |
|
|
| `v3.1.0-beta` | Image variants |
|
|
| `v3.2.0-beta` | Article lists, editor links and activity export |
|
|
| `v3.2.1-beta` | Paged media library and remembered page sizes |
|