shiplog 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a624887b92e388e7234f1c9051437c7c8732b624f448ae4ed6a50834668835b3
-  data.tar.gz: 1a0f18b1f55b919bf9fcf04da75379666428a49fd312c75ea55c6d064e613959
+  metadata.gz: 206caa4e4f1cb0fd09d97cb6f9814711717be5ec45390818e2d6c696f35a9616
+  data.tar.gz: caecf4ba5dbc89c540c9d61c6068bbd619a4060ca4d2754708f749db6925ca09
 SHA512:
-  metadata.gz: 3dd499eff9f0656078de85134f584ee13eddea6e98d9ad431d363da5bb4c53ce8c06c784914fc4ad2fdf5f30a4a2bc9c53632eed87b3dae1bbbd907efb1cfc88
-  data.tar.gz: c2322fb8cde5158aa51656e04d885faede534ab939e0a83677245ea1ab6130d11806cc7145f456f9b211b6b8fe7d2b7e821c198261660b23fe974db1dfee8226
+  metadata.gz: 9332cc8eda030eccc633b5d24ecd1f5ebcdaf6e1526cae056870db680e2559faa9f71e58c0670aafa7b4f05a05f1fb323a46e39faaa6c480c35d509947f02f60
+  data.tar.gz: 3b182cf640dcc187afa77194959712653e91b5ad8187ffe62eb8bd42b813c15ecf9fecd09e248fb23b76cb1e951011531f958facaaeda66c25f2e28ead4c5a49

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.4.0 (2026-10-27)
+
+### Added
+
+- Monthly announcements ([#8](https://github.com/Trackberry/shiplog/issues/8)). A new entry kind, `announcement`, summarises a month: an intro, highlights linking to their permalinks and an "Also improved" list by area, in Markdown. `config.rewriter` drafts it from the month's approved features and changes and the small changes that got no entry (changes discarded as not customer-facing, merged pull requests without an entry, minus excluded labels and authors). Its subject is a new `Shiplog::Period` (one row per month), so drafting is idempotent. Without a rewriter the draft is a skeleton of the month's entries.
+- `Shiplog::DraftAnnouncementJob` (schedule it monthly; it drafts the previous month and skips a month with nothing approved), `bin/rails shiplog:draft_announcement MONTH=2026-10`, and "Draft announcement for <month>" buttons in the inbox for the current and previous month.
+- `config.announcements`: `:page` (default) renders `/changelog/2026-10`, links it from the month's heading ("Read the October 2026 summary") and adds it to the Atom feed (not to `?area=` feeds); `:external` publishes no page and links the month heading to `config.announcement_url = ->(announcement, locale) { url }`; `false` turns announcements off. Features and changes never get a `YYYY-MM` slug, so an announcement's URL is known when it is drafted (a pre-0.4.0 entry holding one makes the announcement use `YYYY-MM-update`).
+- `config.on_announcement_approved = ->(announcement) { ... }` and the `announcement_approved.shiplog` notification, from `Shiplog::AnnounceJob`, once an announcement is approved and every configured locale has a current translation; once per approval (`shiplog_entries.announced_at`). Announcements offer `to_markdown(locale)`, `to_html(locale)`, `to_text(locale)` and `public_url`.
+- The announcement's admin page: a rendered preview, Markdown, HTML and plain-text exports per locale, and whether your app was notified. The inbox flags an announcement whose month's entries changed since it was drafted.
+- `Shiplog.unseen_announcements_count(since:)` and `shiplog_unseen_announcements_count(since)`, for a badge on the monthly summary rather than every entry. `config.on_changelog_seen` also runs on announcement pages, and public controllers expose `shiplog_entry` (the entry viewed).
+- `Shiplog::Markdown.to_html` and `.to_text`: a small renderer that escapes everything it does not build (headings, paragraphs, lists, links and images with safe URLs only, emphasis, code, quotes, rules).
+- New `config.classes` keys: `announcement`, `announcement_title`, `announcement_body`, `month_announcement`, `month_announcement_link`.
+- Newsletter ([#8](https://github.com/Trackberry/shiplog/issues/8), off by default: `config.newsletter`). The approved announcement is emailed, in each recipient's language, to the host's users who opted in (`config.newsletter_recipients`, a callable; Shiplog stores nothing about them) and to the visitors who subscribed through Shiplog's form (`shiplog_newsletter_subscribers`, double opt-in with a 7-day signed link, the same answer whatever the address's state, a honeypot and `rate_limit` per address and IP). The form is on the changelog and announcement pages and `shiplog_newsletter_form` (`Shiplog::NewsletterHelper`) renders it anywhere.
+- Unsubscribing: every newsletter carries the RFC 8058 one-click headers pointing at `POST /shiplog/newsletter/unsubscribe/<encrypted email>`, one endpoint for both lists, which records a suppression row in Shiplog (holding that one email, also for the host's users) and calls `config.on_newsletter_unsubscribe = ->(email) { ... }`; a suppressed address is skipped at send time whatever the host's list says, and `Shiplog::Newsletter.resubscribe(email)` lifts the suppression when a user opts in again. The footer links the same page (a button, nothing changes on a GET), `config.newsletter_unsubscribe_url` for the host's users, and a token-based preferences page for subscribers (language, unsubscribe, resubscribe, delete my data; the token is rotated after each change). The unsubscribe and preferences pages keep working while the newsletter is off. Tokens are encrypted (nothing readable in links or logs); `Shiplog::Newsletter::Tokens.rotate(old_secret_key_base)` keeps old links valid after a secret rotation. Confirmation links are single use. Log lines and the rate-limit cache carry digests of addresses, never addresses.
+- Sending, from the announcement's admin page: "Send a test" to the admin's address in a chosen locale (delivered in the request, so no job holds the address), and "Send…" with a confirmation step (recipients per locale) that enqueues `Shiplog::SendNewsletterJob`. Send is disabled, with the reasons shown, until the announcement is approved, every configured locale has a current translation, and `config.newsletter_from`, `config.newsletter_address` and `config.canonical_url` are set. One email per recipient, at most once (`shiplog_newsletter_deliveries`: recipient key, locale and outcome, no address, inserted before the send and purged after 180 days), merged and deduplicated by email (the host's recipient wins), read in batches of `config.newsletter_batch_size` (500) and claimed 100 at a time; sent, failed and pending counts, and "Retry failed" (an atomic reclaim; a reclaimed recipient that is gone ends as failed). Send, Send test and Retry disable their button once submitted (a small `once.js`; the server is idempotent without it).
+- The newsletter email: a hero (wordmark or logo, month label, title, intro), one highlight card per feature of the month (up to three: screenshot, title, first sentence, "See how it works" button to its page; `Newsletter::Content#highlights`), the rest of the body ("Also improved") and the changelog button. The cards replace the body's first `## ` section when the body has two or more (the split rule, documented in the README); otherwise the body is shown whole. Overriding templates get `@content.highlights`, `intro_html`, `rest_html` and `highlights_shown?`.
+- `Shiplog::NewsletterMailer` (HTML in one 600px table column with inline styles and a text part, `List-Unsubscribe` and `List-Unsubscribe-Post` headers, `config.newsletter_mailer_options` such as Postmark's `message_stream`, branding through `config.newsletter_logo_url` and `config.newsletter_accent`), its overridable templates under `shiplog/newsletter_mailer/`, and `Shiplog::NewsletterMailerPreview` (add `lib/shiplog/previews` to `action_mailer.preview_paths`). `Shiplog::Markdown.to_html` takes `styles:` for inline-styled tags.
+- The admin's Newsletter page: subscriber counts per locale and status, a searchable list with remove, and a CSV export that neutralises formula-looking cells. `Shiplog::PurgeNewsletterJob` and `bin/rails shiplog:purge_newsletter` delete the pending subscribers older than 30 days.
+- New `config.classes` keys: `newsletter`, `newsletter_title`, `newsletter_hint`, `newsletter_form`, `newsletter_label`, `newsletter_input`, `newsletter_button`, `newsletter_notice`. New I18n keys under `shiplog.newsletter` and `shiplog.admin.newsletter` (en and es).
+
+### Changed
+
+- `Shiplog::Drafter.draft` takes extra attributes for a new entry. The changelog's `_month` partial takes an optional `announcement:` local. Translations keep Markdown and link URLs.
+- `Shiplog::Period.month_name(date, locale:)` names a month in any locale (English without month names); `Period#title` uses it. `Shiplog::PublicLinks.path` gives an engine route's path with the mount prefix.
+
+### Upgrading
+
+- Run `bin/rails shiplog:install:migrations` and `bin/rails db:migrate` (adds `shiplog_periods` and `shiplog_entries.announced_at`, then `shiplog_newsletter_subscribers` and `shiplog_newsletter_deliveries`). Rails reports no pending migration for an engine's migrations that were never copied.
+- To send the newsletter: `config.newsletter = true`, `newsletter_from`, `newsletter_address` and `canonical_url`, plus `newsletter_recipients` and `on_newsletter_unsubscribe` for your own users, and `Shiplog::Newsletter.resubscribe(email)` where a user opts in again (see the README's Newsletter section). Give production a real `Rails.cache` (the subscribe form's rate limits count with it) and schedule `Shiplog::PurgeNewsletterJob` weekly. The newsletter's public pages live under `/shiplog/newsletter/`: a route constraint around the engine's mount must let `/shiplog/` paths through, as the webhook already needs. Shiplog stores one row per address that unsubscribes, your users' included: mention it in your privacy policy.
+- With a custom `config.public_layout` or `config.classes`, style the `shiplog-newsletter*` classes (the subscribe form on the changelog and announcement pages, and the newsletter's pages). A host overriding `shiplog/changelogs/show` or `shiplog/changelog_entries/announcement` should render `shiplog/newsletter/form` to offer the form.
+- A custom `config.prompt_builder` now also receives `kind: "announcement"`, with a different context (`month`, `entries`, `skipped`). Return `nil` for it to use the built-in prompt, or build an announcement prompt asking for a Markdown body.
+- With `config.announcements = :page`, `/changelog/YYYY-MM` answers once that month's announcement is approved. A host route of that shape below the changelog path, declared after the mount, is shadowed for those months.
+- Area detection never classifies announcements, and the changelog's "small changes" for an announcement leave out pull requests of a public issue's tree.
+- Schedule `Shiplog::DraftAnnouncementJob` (see the README's Scheduling section), or set `config.announcements = false`.
+- With a custom `config.public_layout` or `config.classes`, style the new classes. A host overriding `shiplog/changelogs/_month` should render the announcement link (see the engine's partial).
+
 ## 0.3.2 (2026-10-26)
 
 0.3.1 hosts should upgrade.

data/README.md

@@ -122,6 +122,19 @@ All settings live in `config/initializers/shiplog.rb`:
 | `images` | `true` | [Screenshots](#screenshots) in entries. Effective only when Active Storage is loaded in the host; `false` turns fetching, upload and rendering off. `true` or `false`, anything else raises `ArgumentError`. |
 | `max_images_per_entry` | `4` | How many images are fetched from the GitHub body of a draft. A non-negative Integer; `0` fetches none (admin uploads are not capped). |
 | `locales` | `[]` | Locales entries are translated into when approved, e.g. `[:es]`. An Array of Symbols or Strings (stored as symbols; the default locale `I18n.default_locale` is dropped); anything else raises `ArgumentError`. See [Translations](#translations). Part of the ETag. |
+| `announcements` | `:page` | Where [monthly announcements](#monthly-announcements) are published: `:page`, `:external` or `false`. Anything else raises `ArgumentError`. Part of the ETag. |
+| `announcement_url` | `nil` | With `announcements = :external`, `->(announcement, locale) { url }` evaluated in the view: where the month heading's summary link goes. |
+| `on_announcement_approved` | `nil` | `->(announcement) { ... }`, called once an announcement is approved and translated. See [Monthly announcements](#monthly-announcements). |
+| `newsletter` | `false` | Emails the approved announcement to your opted-in users and to the visitors who subscribed. `true` or `false`, anything else raises `ArgumentError`. Needs announcements. Part of the ETag. See [Newsletter](#newsletter). |
+| `newsletter_recipients` | `nil` | `-> { User.where(newsletter: true) }`: your users who opted in, each responding to `email`, `locale` and `id` (a relation is read in batches). Never stored. |
+| `newsletter_unsubscribe_url` | `nil` | `->(recipient) { url }`: your own settings page, linked as "Preferences" in your users' emails. Must be an absolute http(s) URL; a failure is logged and the footer links Shiplog's page. |
+| `on_newsletter_unsubscribe` | `nil` | `->(email) { ... }`, called with the lowercased address on every unsubscribe (one-click, link or preferences page) so your list follows; Shiplog suppresses the address itself either way. Errors are logged. Warned about at boot when missing with `newsletter_recipients`. |
+| `newsletter_from` | `nil` | The sender, e.g. `"Acme <updates@acme.com>"`; also used by the confirmation email. Falls back to `ActionMailer::Base.default[:from]`. Required to send. |
+| `newsletter_address` | `nil` | The postal address in the footer, required to send (CAN-SPAM). |
+| `newsletter_logo_url` | `nil` | The logo in the email, an absolute http(s) URL shown 140px wide. Anything else raises `ArgumentError`. |
+| `newsletter_accent` | `nil` | The colour of buttons and links in the email, `"#rrggbb"` (default `#0969da`). Anything else raises `ArgumentError`. |
+| `newsletter_mailer_options` | `{}` | A Hash merged into every newsletter message's `mail(...)`: `{ message_stream: "broadcast" }` for a Postmark broadcast stream, `delivery_method_options`, ... Keys that would change the recipients, the sender or the content (`to`, `cc`, `bcc`, `from`, `reply_to`, `subject`, `body`, `template_name`, ...) raise `ArgumentError`. Not applied to the confirmation email. |
+| `newsletter_batch_size` | `500` | How many recipients a send reads at a time (1 to 10,000); rows are claimed and emailed 100 at a time within. |
 | `max_areas` | `8` | How many [product areas](#product-areas) the AI may create. Past it, entries can only join existing areas. A non-negative Integer; `0` stops the AI creating areas. |
 
 Example:
@@ -205,10 +218,12 @@ Requests are verified with `X-Hub-Signature-256`; an invalid signature returns 4
 
 ## Scheduling
 
-Webhooks can be missed, so schedule two jobs:
+Webhooks can be missed, so schedule these jobs:
 
 - `Shiplog::SyncJob`: reconciles issues and pull requests and creates missing drafts. Every 30 minutes is a good start. The first run backfills everything.
 - `Shiplog::ScanChangesJob`: looks at default-branch commits without a pull request, then drafts small changes. Run it weekly.
+- `Shiplog::DraftAnnouncementJob`: drafts the previous month's [announcement](#monthly-announcements). Run it early each month, after the month's last weekly scan if you can.
+- `Shiplog::PurgeNewsletterJob` (with `config.newsletter`): deletes the [newsletter](#newsletter) subscribers who never confirmed within 30 days and the delivery rows older than 180 days. Run it weekly.
 
 GoodJob (`config/initializers/good_job.rb` or `config/application.rb`):
 
@@ -216,7 +231,9 @@ GoodJob (`config/initializers/good_job.rb` or `config/application.rb`):
 config.good_job.enable_cron = true
 config.good_job.cron = {
   shiplog_sync: { cron: "*/30 * * * *", class: "Shiplog::SyncJob" },
-  shiplog_scan_changes: { cron: "0 6 * * 1", class: "Shiplog::ScanChangesJob" }
+  shiplog_scan_changes: { cron: "0 6 * * 1", class: "Shiplog::ScanChangesJob" },
+  shiplog_announcement: { cron: "0 7 2 * *", class: "Shiplog::DraftAnnouncementJob" },
+  shiplog_purge_newsletter: { cron: "0 5 * * 1", class: "Shiplog::PurgeNewsletterJob" }
 }
 ```
 
@@ -230,6 +247,12 @@ production:
   shiplog_scan_changes:
     class: Shiplog::ScanChangesJob
     schedule: every monday at 6am
+  shiplog_announcement:
+    class: Shiplog::DraftAnnouncementJob
+    schedule: at 7am on the 2nd day of every month
+  shiplog_purge_newsletter:
+    class: Shiplog::PurgeNewsletterJob
+    schedule: every monday at 5am
 ```
 
 You can also trigger a sync from the admin Sync page. Rewriting always runs in `Shiplog::RewriteEntryJob`, never in a request.
@@ -487,6 +510,150 @@ The count is one `COUNT` query over the `(status, approved_at)` index. It filter
 
 `on_changelog_seen` runs **before the page renders**, on the changelog index and on permalink pages whose entry exists, for 200 and 304 answers alike (a visitor whose browser revalidates its cached page has still seen the changelog). Running first means a navbar badge rendered in the same response shows the count after your update. It does not run for 404s (an unknown permalink, a page past the last one), the feed, the roadmap or non-HTML formats. Because it runs on every visit and **may write**, keep it cheap: write only when the stored time is older than the newest entry, as in the example above (one `COUNT`, and a write only when there is something new). The response is not sent yet, so the callback can still set a cookie. An exception in the callback is logged with its class, message and the first five backtrace lines, never shown. A host layout that shows the unseen count renders per-user content, so declare `etag { current_user&.changelog_seen_at }` on your `public_parent_controller`, or a cached page keeps showing the old count.
 
+## Monthly announcements
+
+Once a month, Shiplog drafts a short **announcement** of what shipped: an intro, two or three highlights linking to their permalink pages, and an "Also improved" list grouped by product area. Your `config.rewriter` writes it, in Markdown, from the month's approved features and changes and from the small changes that got no entry of their own (changes the AI judged not customer-facing, and merged pull requests without an entry). An admin edits and approves it like any other entry. Nothing is public before that.
+
+The changelog stays the daily stream. The announcement is its monthly summary.
+
+**Drafting.** Schedule `Shiplog::DraftAnnouncementJob` early each month (see [Scheduling](#scheduling)). It drafts the previous month, once: running it again does nothing. A month without an approved feature or change gets no draft. The inbox also has "Draft announcement for <month>" buttons for the current and the previous month, and `bin/rails shiplog:draft_announcement MONTH=2026-10` drafts any month. Without a rewriter, the draft is a skeleton listing the month's entries with links, ready to edit, and Regenerate rebuilds it from the month's current entries. A month drafted from the button before it ended is not drafted again by the job: regenerate it once the month is over.
+
+An announcement belongs to a month, so its page is `/changelog/2026-10`. The `YYYY-MM` slug is set when it is drafted, and features and changes never get a slug of that shape. If a month's entries change after the draft was written, the inbox flags "The month's entries changed since this draft": regenerate it, or edit it. Regenerating an approved announcement returns it to draft, as for other entries.
+
+**Where it is published** is `config.announcements`:
+
+| Value | What happens |
+|---|---|
+| `:page` (default) | Shiplog renders `/changelog/2026-10`, links it from the month's heading on the changelog ("Read the October 2026 summary") and adds it to the Atom feed. |
+| `:external` | No Shiplog page. The month's heading links to `config.announcement_url`, and your app publishes the text itself through the hook below. |
+| `false` | No announcements: nothing is drafted, rendered or announced. |
+
+```ruby
+config.announcements = :external
+config.announcement_url = ->(announcement, locale) { main_app.blog_post_path(announcement.slug, locale:) }
+```
+
+`announcement_url` is evaluated in the view, so route helpers work. A nil or unsafe result renders no link. Bump `config.cache_version` when its output changes.
+
+**The approval hook.** `config.on_announcement_approved` is called with the announcement once it is approved **and** translated into every configured locale (right after approval with no `config.locales`, or with no rewriter to translate). It runs once per approval, in `Shiplog::AnnounceJob`: an announcement regenerated and approved again is announced again. The hook runs inside the announcement's row lock and is only marked done when it returns, so a hook that raises, or a worker that dies during it, is called again by the retry (twice at most). Keep it fast and idempotent: enqueue your own job, as below. The same moment sends an `announcement_approved.shiplog` ActiveSupport notification with `announcement:` in the payload. If the hook gave up, or a translation never arrived, the admin page has a "Notify now" button, which does not wait for translations (missing ones fall back to English). Editing an approved announcement's text does not call the hook again.
+
+```ruby
+config.on_announcement_approved = ->(announcement) { BlogImportJob.perform_later(announcement.id) }
+```
+
+The announcement is a `Shiplog::Entry` that offers what you need to publish it elsewhere, in the default locale or any configured one:
+
+```ruby
+announcement.display_title(:es) # the Spanish title, or English without a current translation
+announcement.to_markdown(:es)   # the body as written (Markdown)
+announcement.to_html(:es)       # rendered and escaped, safe to embed
+announcement.to_text(:es)       # plain text, e.g. for an email's text part
+announcement.public_url         # its Shiplog page (absolute with config.canonical_url)
+announcement.slug               # "2026-10"
+```
+
+**Export.** The announcement's admin page has a preview, and Markdown, HTML and plain-text downloads in each locale, for blogs and newsletter tools without an API.
+
+**Badge.** `Shiplog.unseen_announcements_count(since:)` (and `shiplog_unseen_announcements_count(since)` in views) counts approved announcements, where `Shiplog.unseen_count` counts every feature and change. Badge the rare monthly summary rather than every daily entry. `config.on_changelog_seen` also runs on an announcement's page, and `controller.shiplog_entry` is the entry being viewed, so you can stamp a separate "announcements seen" time:
+
+```ruby
+config.on_changelog_seen = lambda do |controller|
+  user = controller.send(:current_user)
+  next unless user
+
+  if controller.shiplog_entry&.announcement?
+    user.update_column(:announcements_seen_at, Time.current) if Shiplog.unseen_announcements_count(since: user.announcements_seen_at).positive?
+  elsif Shiplog.unseen_count(since: user.changelog_seen_at).positive?
+    user.update_column(:changelog_seen_at, Time.current)
+  end
+end
+```
+
+**Translations** follow the entries' flow: an approved announcement is translated into `config.locales`, keeping its Markdown and links.
+
+**Styling.** The page uses `shiplog-announcement`, `shiplog-announcement__title` and `shiplog-announcement__body`; the month link uses `shiplog-month__announcement` and `shiplog-month__announcement-link`. All are `config.classes` keys. The body's HTML comes from a small built-in Markdown renderer (headings, paragraphs, lists, links, images, emphasis, code, quotes) that escapes everything else.
+
+**Prompt.** `config.prompt_builder` receives `kind: "announcement"` and a context Hash: `month`, `entries` (each with `kind`, `title`, `body`, `area`, `url`) and `skipped` (titles). Ask for `{"title": "...", "body": "..."}` with a Markdown body, or return `nil` for this kind to keep the built-in prompt.
+
+**Links** in the draft are the entries' permalink URLs, absolute when `config.canonical_url` is set (set it: the text travels to the feed, exports and your hook). With the engine mounted under an optional segment (`scope "(:locale)"`), they are the default locale's URLs.
+
+## Newsletter
+
+Optional, off by default. The approved announcement goes out by email, in each recipient's language, to your users who opted in and to the visitors who subscribed through Shiplog's form. Approving publishes the announcement; sending the newsletter is a separate, explicit action on the announcement's admin page.
+
+**Setup.**
+
+```ruby
+Shiplog.configure do |config|
+  config.newsletter         = true
+  config.newsletter_from    = "Acme <updates@acme.com>"
+  config.newsletter_address = "Acme Inc., 123 Main Street, Springfield"   # the footer's postal address (CAN-SPAM)
+  config.canonical_url      = "https://acme.com"                          # the links in emails are absolute
+  config.newsletter_logo_url = "https://acme.com/logo.png"                 # optional branding
+  config.newsletter_accent   = "#0969da"
+end
+```
+
+Then run the migrations (`bin/rails shiplog:install:migrations && bin/rails db:migrate`): the newsletter adds `shiplog_newsletter_subscribers` and `shiplog_newsletter_deliveries`. The admin nav gets a Newsletter page, and the changelog and announcement pages get a subscribe form. At boot, Shiplog logs what is still missing to send.
+
+**Recipients: your users.** Shiplog never stores them. Give it a callable returning objects that respond to `email`, `locale` and `id` (an Active Record relation is read in batches), and two hooks so an unsubscribe reaches your side too:
+
+```ruby
+config.newsletter_recipients      = -> { User.where(newsletter: true) }
+config.newsletter_unsubscribe_url = ->(user) { Rails.application.routes.url_helpers.settings_url(host: "acme.com") }   # optional
+config.on_newsletter_unsubscribe  = ->(email) { User.where("lower(email) = ?", email).update_all(newsletter: false) }
+```
+
+You own the opt-in, the settings toggle and the locale: resolve it yourself (for Trackberry: the user's locale, then the organization's default, then English). A locale that is not the default nor one of `config.locales` gets the default language. Objects without a usable email or id are skipped with a warning (which names no address).
+
+How an unsubscribe works for your users: every newsletter carries the RFC 8058 one-click headers (`List-Unsubscribe` and `List-Unsubscribe-Post`, which Gmail and Yahoo require from bulk senders) pointing at Shiplog's own endpoint, `POST /shiplog/newsletter/unsubscribe/<token>`, where the token is the recipient's email, encrypted and signed with a key derived from your app's `secret_key_base` (nothing in a link or a log reveals the address). So Shiplog needs no row for your users until they unsubscribe, and one endpoint serves both lists: it records the unsubscribe in Shiplog, as a *suppression row* in `shiplog_newsletter_subscribers` holding that one email (created when the address has no row, marked when it has), and calls `on_newsletter_unsubscribe` with the lowercased email so your own setting follows. From then on the address is skipped at send time even if your list still returns it: an unsubscribe is honoured whether or not your hook works. Set the hook anyway (Shiplog warns at boot when `newsletter_recipients` is set without it), or your settings page will show the user as subscribed. When a user opts in again in your app, lift the suppression:
+
+```ruby
+Shiplog::Newsletter.resubscribe(user.email)   # true when the address was suppressed
+```
+
+A suppression-only row is deleted (nothing is left to store); a visitor who had confirmed through Shiplog's form is confirmed again. The footer's "Unsubscribe" link opens the same endpoint as a page with a button (a GET changes nothing: mail scanners prefetch links). The footer's "Preferences" link is `newsletter_unsubscribe_url` when you set it (your own settings page, evaluated with the recipient object), else Shiplog's unsubscribe page. These pages keep working after you turn `config.newsletter` off (or announcements): a link in an old email must still unsubscribe. If you rotate `secret_key_base`, call `Shiplog::Newsletter::Tokens.rotate(old_secret_key_base)` in an initializer while old links must keep working.
+
+**Recipients: visitors.** The subscribe form is on the changelog and on each announcement page, and you can render it on any page:
+
+```erb
+<%# a host view; add `helper Shiplog::NewsletterHelper` to the controller %>
+<%= shiplog_newsletter_form %>
+```
+
+One email field, a hidden honeypot, a plain POST that works without JavaScript. Double opt-in: the form creates a pending subscriber with the page's locale (if it is the default or one of `config.locales`) and the page it was on (`source`, a consent record: a same-site path, anything else is dropped), and emails a confirmation link valid 7 days; the link opens a page with a button, and the button confirms. The link is single use (an encrypted nonce, spent when it confirms, voided by an unsubscribe, replaced when a new confirmation is sent), so a replayed link resubscribes nobody. Only confirmed subscribers receive the newsletter. The form answers the same thing for a new, pending, confirmed or unsubscribed address, so it reveals nothing; a confirmed address gets no new email, and an existing row keeps its locale and source (an anonymous submission cannot rewrite them). Attempts are rate limited per address (3 an hour, keyed by a digest of the address without `+tag` and, for Gmail, without dots), per IP (20 an hour) and overall (300 confirmation emails an hour) through `Rails.cache`: with a null store nothing is counted, so give production a real cache store (Shiplog warns at boot otherwise). The subscribe POST carries no CSRF token and checks none: the pages carrying the form are served with ETags, so a cached page could hold a stale token, and nothing happens until the address confirms by email.
+
+Every newsletter links a preferences page, reached through a token in the URL without an account, where a subscriber changes the language, unsubscribes, resubscribes (no new confirmation: the token proves the mailbox) or deletes their data. The token is rotated after each change there (the page continues with the new one; the link in the old email stops working, the next newsletter carries the new one). Unsubscribed rows stay as a suppression record; subscribing again through the form means confirming again. Schedule `Shiplog::PurgeNewsletterJob` weekly (see [Scheduling](#scheduling)): it deletes pending rows untouched for 30 days and delivery rows older than 180 days. `bin/rails shiplog:purge_newsletter` does the same.
+
+**One person on both lists.** Recipients are merged at send time and deduplicated by lowercased email; when an address is on both lists, your user wins (its locale, its preferences link). Any unsubscribe removes the address from both.
+
+**Sending.** On an approved announcement's admin page: "Send a test to <your address>" (`config.current_admin`'s email, in a chosen locale; works before approval) and "Send…", which opens a confirmation step with the recipient count per locale and sends through `Shiplog::SendNewsletterJob`. Send stays disabled, with the reasons on the page, until the announcement is approved, every configured locale has a current translation (no stale translation is ever sent), and `newsletter_from`, `newsletter_address` and an origin for links (`canonical_url`, else `action_mailer.default_url_options`) are set. The job renders the body once per locale and emails each recipient once: a `shiplog_newsletter_deliveries` row (unique on announcement and recipient key, no address) is inserted *before* the email leaves, 100 recipients at a time, and touched right before each send, so a retried job, two workers or a second click never send twice. This is at-most-once: a worker dying between the insert and the send leaves a pending row, never a duplicate. The page shows sent, failed and pending counts; "Retry failed" reclaims, in one statement, the failed rows and the rows left pending for more than an hour, and sends them again (the one case where a recipient may get the email twice, and you trigger it knowingly); a reclaimed row whose recipient is gone (unsubscribed, deleted) ends as failed with that reason. Failures are recorded as the exception's class and its message with anything address-like removed. One newsletter per announcement: a later Send only reaches recipients added since.
+
+**Deliverability.** Send bulk mail through a separate stream, so a complaint never hurts your transactional email. With Postmark:
+
+```ruby
+config.newsletter_mailer_options = { message_stream: "broadcast" }
+config.newsletter_batch_size     = 500   # the default; how many recipients a run claims at a time
+```
+
+`newsletter_mailer_options` is merged into every newsletter message (not the confirmation email, which is transactional and uses your default delivery settings): ActionMailer options (`delivery_method`, `delivery_method_options`) or headers your delivery gem reads. Also: set up SPF, DKIM and DMARC for the sending domain, keep the postal address in the footer, and let Postmark (or your provider) suppress bounces and complaints per stream. Shiplog adds `Precedence: bulk` and the one-click headers; it does no open or click tracking.
+
+**Design.** `Shiplog::NewsletterMailer` builds an HTML part (one 600px table column, fluid on phones, every style inline, absolute image URLs with width and alt, light colours that email clients invert sanely in dark mode) and a text part. The email: a logo row (or the product name as a wordmark) with "View in browser", a hero card with "Monthly update · October 2026", the title and the intro, then one **highlight card** per feature of the month (up to three, in the changelog's order): its first screenshot full width when it has one, its title, its first sentence and a "See how it works" button to its page; then a card with the rest of the announcement ("Also improved", grouped by area), a "See everything that shipped" button, and the footer with unsubscribe, preferences and the postal address. The subject, title and body are the announcement's translation in the recipient's locale (English without one); the chrome uses Shiplog's I18n keys under `shiplog.newsletter` (en and es shipped). "View in browser" opens the announcement's page (`config.announcement_url`, called with the entry and the locale, when announcements are `:external`).
+
+**Highlights and the body.** The cards come from the month's approved features themselves (their approved, translated title and body, their screenshot and permalink; features without a permalink are skipped), not from the announcement's text, so an edit to the body's highlights section does not show in the cards. To avoid saying everything twice, the email applies a split rule: when there are highlights and the body has at least two `## ` sections, it shows the intro (the text before the first heading), the cards in place of the body's *first* section, and the body from its *second* section on. Otherwise (no feature with a permalink, or a body without that structure) the whole body is shown as written. The split is made on the Markdown of the locale's text, so translated headings work the same. Screenshots need `config.images`; their URLs go through Active Storage's redirect route of your app at the email's origin (`canonical_url`), and a screenshot whose URL cannot be built is left out with a log line.
+
+**Customising the email.** Copy `app/views/shiplog/newsletter_mailer/announcement.{html,text}.erb` (and `confirmation.{html,text}.erb`) into your app, both parts of each: Rails takes a mailer's templates from the first view path that has any, so an app holding only the HTML part sends a single-part email. The templates get `@content`, a `Shiplog::Newsletter::Content` with `title`, `month`, `preheader`, `html` (the whole body, inline-styled), `highlights_shown?` (the split rule applies), `intro_html` / `intro_text`, `highlights` (each with `title`, `summary`, `url`, `image_url`, `image_alt`, `image_width`, `image_height`, `image?`), `rest_html` / `rest_text`, `text`, `view_url`, `changelog_url`, `accent`, `logo_url`, `address` and `product_name`; plus `@unsubscribe_url` and `@preferences_url`. `Shiplog::NewsletterMailerHelper` offers `shiplog_mail_palette`, `shiplog_mail_font`, `shiplog_mail_button(label, url, accent)` and `shiplog_mail_screenshot(highlight)`, and `Shiplog::Markdown.to_html(text, styles: { "p" => "..." })` renders Markdown with inline styles. An override must keep the unsubscribe link (`@unsubscribe_url`), the preferences link and the postal address (`@content.address`): the `List-Unsubscribe` headers are set by the mailer, but the footer is the recipient's visible way out and the address is required by CAN-SPAM. To preview locally, add the previews to `config/environments/development.rb` and open `/rails/mailers/shiplog/newsletter_mailer` (the sample shows three cards without any data):
+
+```ruby
+config.action_mailer.preview_paths << Shiplog::Engine.root.join("lib/shiplog/previews").to_s
+```
+
+**Admin.** The Newsletter page lists the subscribers (counts per locale and status, search, remove) and downloads them as CSV (cells that a spreadsheet would read as a formula are neutralised). Your own users are not listed: they are yours.
+
+**What Shiplog stores, and consent.** In `shiplog_newsletter_subscribers`: the visitors who subscribed through its form (email, locale, the page they subscribed on, when they subscribed, confirmed and unsubscribed, the preferences token and a pending confirmation nonce), and one row per address that unsubscribed, your users' included: the suppression record that keeps the address out of future sends, holding the email and the time (no locale of yours, no source). Nothing else about your users, and no tracking of opens or clicks. Delivery rows (`shiplog_newsletter_deliveries`) keep the recipient key (`User/42` or `Subscriber/7`), the locale and the outcome, never the address; they are deleted with a subscriber's row, with the announcement, and after 180 days by the purge job. Log lines name recipient keys or a digest of the address, never the address; the rate-limit cache holds digests. A suppression row stays until the person deletes their data from the preferences page, an admin removes it, or your app calls `Shiplog::Newsletter.resubscribe`. No queued job carries an address: a test send is delivered in the request, a confirmation's job carries the subscriber's id, and the send job reads its recipients when it runs. Mention the newsletter in your privacy policy.
+
+**Styling.** The form and pages use `shiplog-newsletter` with `__title`, `__hint`, `__form`, `__label`, `__input`, `__button` and `__notice`, all `config.classes` keys (`newsletter`, `newsletter_title`, ...). The honeypot sits in `shiplog-newsletter__trap`, which the bundled stylesheet moves out of view: keep a rule for it if you style the pages yourself.
+
 ## Styling
 
 The public pages ship plain semantic HTML with stable [BEM](https://getbem.com) classes (`shiplog-card`, `shiplog-entry__title`, ...) and a small, framework-free stylesheet. Pick the level that fits your app; the same views work in all of them.
@@ -624,6 +791,7 @@ Copy any view from the engine's `app/views/shiplog/` into your app with the same
 - `shiplog/_switcher.html.erb`
 - `shiplog/roadmaps/_column.html.erb`, `shiplog/roadmaps/_card.html.erb`, `shiplog/roadmaps/_shipped.html.erb`
 - `shiplog/changelogs/_month.html.erb`, `shiplog/changelogs/_entry.html.erb`, `shiplog/changelogs/_search.html.erb`
+- `shiplog/newsletter/_form.html.erb` (the subscribe form), `shiplog/newsletter/_page.html.erb` (the confirm, preferences and unsubscribe pages' frame), and the emails in `shiplog/newsletter_mailer/`
 
 `shiplog/_page.html.erb` is what links the stylesheet (so it also works in layouts you don't control); keep that line if you copy it and still want the bundled CSS.
 

data/app/controllers/shiplog/admin/announcements_controller.rb

@@ -0,0 +1,19 @@
+module Shiplog
+  module Admin
+    # "Draft announcement for <month>" in the inbox: drafts the current or the previous month (see
+    # Announcements.draftable_months) and opens it; a month that has an announcement already opens that one.
+    class AnnouncementsController < ApplicationController
+      def create
+        month = Announcements.draftable_months.find { |candidate| candidate.strftime("%Y-%m") == params[:month].to_s }
+        return head(:not_found) unless month && Shiplog.announcements?
+
+        entry = Announcements.draft(month:) || Period.find_by(starts_on: month)&.announcement
+        if entry
+          redirect_to edit_entry_path(entry, inbox_filter_params), notice: t("shiplog.admin.announcements.drafted")
+        else
+          redirect_to root_path(inbox_filter_params), alert: t("shiplog.admin.announcements.nothing_to_announce")
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/announcement_notifications_controller.rb

@@ -0,0 +1,18 @@
+module Shiplog
+  module Admin
+    module Entries
+      # "Notify now" on an approved announcement your app was not told about yet: the hook gave up after its retries,
+      # or a translation never came. Calls config.on_announcement_approved without waiting for translations (the
+      # hook gets the English text where one is missing); an announcement already announced is left alone.
+      class AnnouncementNotificationsController < ApplicationController
+        def create
+          entry = Entry.find(params[:entry_id])
+          return head(:not_found) unless entry.announcement?
+
+          AnnounceJob.perform_later(entry, force: true)
+          redirect_to edit_entry_path(entry, inbox_filter_params), notice: t("shiplog.admin.announcements.notify_queued")
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/exports_controller.rb

@@ -0,0 +1,45 @@
+module Shiplog
+  module Admin
+    module Entries
+      # An announcement's text as a file, for hosts that publish it on their own blog or newsletter tool:
+      # ?as=markdown (default), html or text, in the default locale or ?export_locale=<one of config.locales>. The text is
+      # the current translation when there is one, else the English text (Entry#to_markdown).
+      class ExportsController < ApplicationController
+        FORMATS = {
+          "markdown" => [ "md", "text/markdown" ],
+          "html" => [ "html", "text/html" ],
+          "text" => [ "txt", "text/plain" ]
+        }.freeze
+
+        def show
+          entry = Entry.find(params[:entry_id])
+          return head(:not_found) unless entry.announcement?
+
+          locale = export_locale
+          return head(:not_found) unless locale
+
+          extension, type = FORMATS.fetch(params[:as].to_s.presence || "markdown") { return head(:not_found) }
+          send_data content(entry, extension, locale), type: "#{type}; charset=utf-8", disposition: "attachment",
+            filename: "#{entry.slug.presence || "announcement-#{entry.id}"}#{"-#{locale}" unless locale == I18n.default_locale.to_s}.#{extension}"
+        end
+
+        private
+
+        # The default locale or a configured one; nil for anything else.
+        def export_locale
+          requested = params[:export_locale].to_s.presence || I18n.default_locale.to_s
+          requested if requested == I18n.default_locale.to_s || Entry.translated_locale?(requested)
+        end
+
+        def content(entry, extension, locale)
+          title = entry.display_title(locale).to_s
+          case extension
+          when "md" then "# #{title}\n\n#{entry.to_markdown(locale)}\n"
+          when "html" then "<h1>#{ERB::Util.html_escape(title)}</h1>\n#{entry.to_html(locale)}\n"
+          else "#{title}\n\n#{entry.to_text(locale)}\n"
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/newsletter_retries_controller.rb

@@ -0,0 +1,17 @@
+module Shiplog
+  module Admin
+    module Entries
+      # "Retry failed": runs Shiplog::SendNewsletterJob again for the deliveries that failed, and for the pending
+      # ones older than an hour (a worker died with them claimed; see NewsletterDelivery.reclaim).
+      class NewsletterRetriesController < ApplicationController
+        def create
+          entry = Entry.find(params[:entry_id])
+          return head(:not_found) unless entry.announcement? && Shiplog.newsletter?
+
+          SendNewsletterJob.perform_later(entry, retry_failed: true)
+          redirect_to edit_entry_path(entry, inbox_filter_params), notice: t("shiplog.admin.newsletter.retry_queued")
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/newsletter_tests_controller.rb

@@ -0,0 +1,39 @@
+module Shiplog
+  module Admin
+    module Entries
+      # "Send test": one copy of the newsletter to the current admin's address (config.current_admin, which gives
+      # an email by default; nothing can be sent when it gives none), in the chosen locale. No delivery row: a
+      # test never counts as a send, and it works before the announcement is approved or translated. The links in
+      # it are real (the admin's own unsubscribe link), as in the final email.
+      class NewsletterTestsController < ApplicationController
+        def create
+          entry = Entry.find(params[:entry_id])
+          return head(:not_found) unless entry.announcement? && Shiplog.newsletter?
+
+          email = current_admin_name.to_s.strip
+          return back_with_alert(entry, t("shiplog.admin.newsletter.test_no_email")) unless URI::MailTo::EMAIL_REGEXP.match?(email)
+
+          blockers = Newsletter.blockers(entry, test: true)
+          return back_with_alert(entry, t("shiplog.admin.newsletter.send_blocked", reasons: blockers.map { |blocker| t("shiplog.admin.newsletter.blockers.#{blocker}", locales: "") }.join(", "))) if blockers.any?
+
+          # test_locale, not locale: a host's around_action switching the locale from params[:locale] must not read it.
+          locale = NewsletterSubscriber.resolve_locale(params[:test_locale])
+          # Delivered now, in the request: a queued mail job would carry the admin's address (and unsubscribe link)
+          # into the queue's storage. One message, so the wait is short, and a failure shows at once.
+          NewsletterMailer.announcement(entry, email, locale:, unsubscribe_url: Newsletter.unsubscribe_url(email)).deliver_now
+          redirect_to edit_entry_path(entry, inbox_filter_params), notice: t("shiplog.admin.newsletter.test_sent", email:, language: locale)
+        rescue StandardError => error
+          # The class only: a delivery error's message can carry the address or the mail server's details.
+          Rails.logger.error("[shiplog] The newsletter test send failed: #{error.class}")
+          back_with_alert(entry, t("shiplog.admin.newsletter.test_failed", error: error.class.name))
+        end
+
+        private
+
+        def back_with_alert(entry, alert)
+          redirect_to edit_entry_path(entry, inbox_filter_params), alert:
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/newsletters_controller.rb

@@ -0,0 +1,40 @@
+module Shiplog
+  module Admin
+    module Entries
+      # Sending an announcement as the newsletter: `show` is the confirmation step (the recipient count per locale,
+      # after deduplication), `create` enqueues Shiplog::SendNewsletterJob. Both refuse while Newsletter.blockers
+      # lists a reason (not approved, a missing translation, no sender, no address, no origin for links).
+      class NewslettersController < ApplicationController
+        before_action :set_announcement
+
+        def show
+          @blockers = Newsletter.blockers(@entry)
+          @progress = NewsletterDelivery.progress(@entry)
+          @counts = Newsletter::Recipients.new.counts_by_locale
+        rescue StandardError => error
+          # The page names the class only: a message could carry an address or a secret. The log has the rest.
+          Rails.logger.error("[shiplog] Listing the newsletter's recipients failed: #{error.class}: #{NewsletterDelivery.scrub(error.message)}")
+          @counts = {}
+          @recipients_error = error.class.name
+        end
+
+        def create
+          blockers = Newsletter.blockers(@entry)
+          if blockers.any?
+            redirect_to edit_entry_path(@entry, inbox_filter_params), alert: t("shiplog.admin.newsletter.send_blocked", reasons: blockers.map { |blocker| t("shiplog.admin.newsletter.blockers.#{blocker}", locales: Newsletter.missing_locales(@entry).join(", ")) }.join(", "))
+          else
+            SendNewsletterJob.perform_later(@entry)
+            redirect_to edit_entry_path(@entry, inbox_filter_params), notice: t("shiplog.admin.newsletter.queued")
+          end
+        end
+
+        private
+
+        def set_announcement
+          @entry = Entry.find(params[:entry_id])
+          head :not_found unless @entry.announcement? && Shiplog.newsletter?
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/translations_controller.rb

@@ -12,6 +12,7 @@ module Shiplog
           translation.assign_attributes(translation_params)
           translation.assign_attributes(edited_by_admin: true, source_digest: @entry.translation_source_digest)
           if translation.save
+            AnnounceJob.perform_later(@entry) if @entry.announcement? # the missing translation may have been this one
             redirect_to edit_entry_path(@entry, inbox_filter_params), notice: t("shiplog.admin.entries.translations.saved", default: "Translation saved.")
           else
             redirect_to edit_entry_path(@entry, inbox_filter_params), alert: translation.errors.full_messages.to_sentence

data/app/controllers/shiplog/admin/entries_controller.rb

@@ -42,9 +42,11 @@ module Shiplog
 
       private
 
-      # Every subject type (issue, pull request, commit) belongs to a repository; load them once per type.
+      # Issues, pull requests and commits belong to a repository (periods don't); load them once per type.
       def preload_repositories(entries)
-        entries.filter_map(&:subject).group_by(&:class).each_value do |subjects|
+        entries.filter_map(&:subject).group_by(&:class).each do |type, subjects|
+          next unless type.reflect_on_association(:repository)
+
           ActiveRecord::Associations::Preloader.new(records: subjects, associations: :repository).call
         end
       end
@@ -53,8 +55,10 @@ module Shiplog
         @entry = Entry.find(params[:id])
       end
 
+      # An announcement's month, release date and area follow from its period: only its text is edited.
       def entry_params
-        params.expect(entry: %i[title body released_on changelog_kind area_id])
+        permitted = params.expect(entry: %i[title body released_on changelog_kind area_id])
+        @entry.announcement? ? permitted.slice(:title, :body) : permitted
       end
 
       def page_number

data/app/controllers/shiplog/admin/newsletter_subscribers_controller.rb

@@ -0,0 +1,47 @@
+module Shiplog
+  module Admin
+    # The newsletter's subscribers (the visitors who subscribed through Shiplog's form; the host's users are its
+    # own): counts per locale and status, a searchable paginated list, removal, and a CSV export (.csv, the
+    # search applied; cells that look like formulas are neutralised, see Newsletter::Csv).
+    class NewsletterSubscribersController < ApplicationController
+      PER_PAGE = 100
+      MAX_PAGE = 100_000
+
+      before_action :require_newsletter
+
+      def index
+        @query = params[:q].is_a?(String) ? params[:q].squish.first(NewsletterSubscriber::EMAIL_MAX_LENGTH) : ""
+        scope = NewsletterSubscriber.search(@query).newest_first
+        respond_to do |format|
+          format.html do
+            @counts = NewsletterSubscriber.counts_by_locale
+            @page = page_number
+            records = scope.offset((@page - 1) * PER_PAGE).limit(PER_PAGE + 1).to_a
+            @more = records.size > PER_PAGE
+            @subscribers = records.first(PER_PAGE)
+          end
+          format.csv do
+            send_data Newsletter::Csv.generate(scope), type: "text/csv; charset=utf-8", disposition: "attachment",
+              filename: "shiplog-newsletter-subscribers-#{Date.current.iso8601}.csv"
+          end
+        end
+      end
+
+      def destroy
+        subscriber = NewsletterSubscriber.find(params[:id])
+        subscriber.destroy!
+        redirect_to newsletter_subscribers_path(q: params[:q].presence), notice: t("shiplog.admin.newsletter.removed", email: subscriber.email)
+      end
+
+      private
+
+      def require_newsletter
+        head :not_found unless Shiplog.newsletter?
+      end
+
+      def page_number
+        Integer(params[:page].to_s, 10, exception: false).to_i.clamp(1, MAX_PAGE)
+      end
+    end
+  end
+end

data/app/controllers/shiplog/changelog_entries_controller.rb

@@ -1,11 +1,13 @@
 module Shiplog
-  # The permalink page of a published feature or change: /changelog/:slug.
+  # The permalink page of a published feature or change, or of a month's announcement: /changelog/:slug.
   class ChangelogEntriesController < PublicController
     def show
-      @entry = Entry.published_changelog.with_images_loaded.find_by(slug: params[:slug])
+      @entry = Entry.published_changelog.with_images_loaded.find_by(slug: params[:slug]) || published_announcement
       return pass_to_host_routes unless @entry
 
       notify_changelog_seen
+      return show_announcement if @entry.announcement?
+
       @newer = @entry.newer_changelog_entry
       @older = @entry.older_changelog_entry
       preload_translations(@entry, @newer, @older)
@@ -15,6 +17,16 @@ module Shiplog
 
     private
 
+    # An approved announcement with this slug, when Shiplog renders announcement pages (config.announcements).
+    def published_announcement
+      Entry.published_announcements.find_by(slug: params[:slug]) if Shiplog.announcement_pages?
+    end
+
+    def show_announcement
+      preload_translations(@entry)
+      render :announcement if stale?(etag: [ *shiplog_etag_parts, @entry.id, @entry.updated_at, shiplog_translation_etag_parts([ @entry ]) ])
+    end
+
     # The engine is usually mounted at "/", so /changelog/:slug can shadow a host route below the changelog
     # path (/changelog/archive, declared after the mount). An unknown slug answers 404 with X-Cascade: pass,
     # which makes the router try the routes after the engine's mount; if none matches, the host's own 404 shows.

data/app/controllers/shiplog/changelog_feeds_controller.rb

@@ -1,5 +1,6 @@
 module Shiplog
-  # The Atom feed of the latest published features and changes: /changelog.atom.
+  # The Atom feed of the latest published features and changes, and of the announcements when Shiplog renders
+  # their pages: /changelog.atom.
   class ChangelogFeedsController < PublicController
     LIMIT = 50
 
@@ -7,7 +8,10 @@ module Shiplog
     before_action :set_area
 
     def show
-      scope = Entry.published_changelog.newest_first
+      scope = Entry.published_changelog
+      # Announcements have no area: a feed filtered by area leaves them out.
+      scope = scope.or(Entry.published_announcements) if Shiplog.announcement_pages? && !@area
+      scope = scope.newest_first
       scope = scope.where(area_id: @area.id) if @area
       @entries = scope.includes(:area).with_images_loaded.limit(LIMIT).to_a
       @entries.select!(&:permalink?) # no slug (or an invalid one) means no stable id: left out