shiplog 0.3.2 → 0.4.0

data/app/controllers/shiplog/changelogs_controller.rb

@@ -21,14 +21,24 @@ module Shiplog
       @months = records.first(PER_PAGE).group_by { |entry| entry.released_on.beginning_of_month }
       @result_count = scope.count if @query
       shown = @months.values.flatten
+      @announcements = announcements_for(@months.keys)
       preload_translations(shown)
       fresh_when etag: [ *shiplog_etag_parts, *shiplog_area_etag_parts, @areas.map(&:id), @query, @page, @older,
         shown.map { |entry| [ entry.id, entry.updated_at, entry.area_id ] },
-        shiplog_image_etag_parts(shown), shiplog_translation_etag_parts(shown) ]
+        shiplog_image_etag_parts(shown), shiplog_translation_etag_parts(shown),
+        @announcements.values.map { |announcement| [ announcement.id, announcement.slug, announcement.updated_at ] } ]
     end
 
     private
 
+    # The approved announcements of the months shown, by the month's first day (none while announcements are off).
+    def announcements_for(months)
+      return {} unless Shiplog.announcements? && months.any?
+
+      Entry.published_announcements.where(released_on: months.map(&:end_of_month))
+        .index_by { |announcement| announcement.released_on.beginning_of_month }
+    end
+
     # The areas to offer as filter links: those with published entries, in the admin's order, and only when there
     # are at least two (a single area filters nothing).
     def filter_areas

data/app/controllers/shiplog/frontends_controller.rb

@@ -5,7 +5,8 @@ module Shiplog
       "shiplog.css" => { path: ASSET_DIRECTORY.join("shiplog.css"), type: "text/css" },
       "admin.css" => { path: ASSET_DIRECTORY.join("admin.css"), type: "text/css" },
       "board.js" => { path: ASSET_DIRECTORY.join("board.js"), type: "text/javascript" },
-      "inbox.js" => { path: ASSET_DIRECTORY.join("inbox.js"), type: "text/javascript" }
+      "inbox.js" => { path: ASSET_DIRECTORY.join("inbox.js"), type: "text/javascript" },
+      "once.js" => { path: ASSET_DIRECTORY.join("once.js"), type: "text/javascript" }
     }.freeze
 
     # The version segment busts caches; stale versions are 404 so they are never cached as the current file.

data/app/controllers/shiplog/newsletter/confirmations_controller.rb

@@ -0,0 +1,27 @@
+module Shiplog
+  module Newsletter
+    # The double opt-in link: a page with a button (GET changes nothing, link scanners prefetch), and the POST
+    # that confirms. The token is signed and expires after 7 days (Newsletter::Tokens); an invalid one is a 404.
+    # Rendered in the subscriber's language, whatever the page's URL.
+    class ConfirmationsController < NewsletterController
+      around_action :with_subscriber
+
+      def show
+      end
+
+      def create
+        @subscriber.confirm!
+        render :create
+      end
+
+      private
+
+      def with_subscriber
+        @subscriber = Tokens.subscriber_for(params[:token])
+        return render_invalid_link unless @subscriber
+
+        I18n.with_locale(Newsletter.i18n_locale(@subscriber.locale)) { yield }
+      end
+    end
+  end
+end

data/app/controllers/shiplog/newsletter/preferences_controller.rb

@@ -0,0 +1,50 @@
+module Shiplog
+  module Newsletter
+    # A subscriber's preferences, reached through the token of the newsletter's footer, without an account:
+    # change the language, unsubscribe, resubscribe (the token proves the mailbox, so no new confirmation), and
+    # "delete my data", which removes the row. The token is rotated after each change (the next page uses the
+    # new one; the link in the old email stops working). Rendered in the subscriber's language, and still
+    # available while config.newsletter is off, so an old email's link keeps working.
+    class PreferencesController < NewsletterController
+      skip_before_action :require_newsletter
+      before_action :require_newsletter_tables
+      around_action :with_subscriber
+
+      def show
+      end
+
+      # locale (one of the allowed ones) and/or subscribed ("0" unsubscribes from both lists, "1" resubscribes).
+      # The notice is worded in the language just chosen, which the next page is in.
+      def update
+        notice = "saved"
+        case params[:subscribed]
+        when "0"
+          Newsletter.unsubscribe(@subscriber.email)
+          notice = "unsubscribed"
+        when "1"
+          @subscriber.resubscribe!
+          notice = "resubscribed"
+        end
+        @subscriber.update!(locale: NewsletterSubscriber.resolve_locale(params[:locale])) if params[:locale].is_a?(String)
+        @subscriber.rotate_token!
+        I18n.with_locale(Newsletter.i18n_locale(@subscriber.locale)) do
+          redirect_to newsletter_preferences_path(@subscriber.token), notice: t("shiplog.newsletter.preferences.#{notice}")
+        end
+      end
+
+      def destroy
+        @subscriber.destroy!
+        render :destroy
+      end
+
+      private
+
+      def with_subscriber
+        @subscriber = NewsletterSubscriber.find_by(token: params[:token].to_s)
+        return render_invalid_link unless @subscriber
+
+        I18n.with_locale(Newsletter.i18n_locale(@subscriber.locale)) { yield }
+      end
+    end
+  end
+end

data/app/controllers/shiplog/newsletter/subscriptions_controller.rb

@@ -0,0 +1,70 @@
+module Shiplog
+  module Newsletter
+    # The subscribe form's target and the "check your inbox" page it leads to.
+    class SubscriptionsController < NewsletterController
+      PER_IP = 20
+      PER_EMAIL = 3
+      # All confirmation emails together, an hour: a ceiling on what a distributed bot can make Shiplog send.
+      GLOBAL = 300
+      WINDOW = 1.hour
+      # The honeypot's field name: nothing a browser autofills (no "website", "url", "phone"...).
+      HONEYPOT = :nl_extra
+
+      # The form sits on public pages that are served with ETags: a 304 revisits a cached page, whose CSRF token
+      # may belong to another session or be expired, and a host layout may cache it further. So the form sends no
+      # token and this action checks none: it changes no session state, and nothing happens until the address
+      # confirms by email (double opt-in), so a forged POST can at most send someone a confirmation email, which
+      # the rate limits bound.
+      skip_forgery_protection only: :create
+
+      # Rails.cache counts the attempts (a null store counts nothing: the limits are then off, as in tests). The
+      # per-address count is keyed by a digest of the normalised address (Newsletter.rate_limit_key), so the cache
+      # holds no address and "a+tag@gmail.com" and "a.b@gmail.com" count as one.
+      rate_limit to: PER_IP, within: WINDOW, by: -> { request.remote_ip }, with: -> { rate_limited }, name: "ip", only: :create
+      rate_limit to: PER_EMAIL, within: WINDOW, by: -> { submitted_email.present? ? Newsletter.rate_limit_key(submitted_email) : request.remote_ip }, with: -> { rate_limited }, name: "email", only: :create
+      rate_limit to: GLOBAL, within: WINDOW, by: -> { "all" }, with: -> { rate_limited }, name: "global", only: :create
+
+      # The same redirect for a new, pending, confirmed or unsubscribed address (and for a bot that filled the
+      # honeypot): the form cannot tell who is subscribed. Only an address that is not an email gets the form back.
+      def create
+        return redirect_to(newsletter_subscription_path) if params[HONEYPOT].present?
+
+        subscriber = NewsletterSubscriber.subscribe(submitted_email, locale: I18n.locale, source: submitted_source)
+        if subscriber
+          redirect_to newsletter_subscription_path
+        else
+          @error = t("shiplog.newsletter.form.invalid_email", default: "Enter a valid email address.")
+          @email = submitted_email
+          render :show, status: :unprocessable_content
+        end
+      end
+
+      # "Check your inbox to confirm."
+      def show
+      end
+
+      private
+
+      def submitted_email
+        value = params[:email]
+        value.is_a?(String) ? value.strip.downcase.first(NewsletterSubscriber::EMAIL_MAX_LENGTH + 1) : ""
+      end
+
+      # The page the visitor subscribed on: the form's `source` when it is a same-site path, else the referrer's
+      # path (NewsletterSubscriber.clean_source has the last word).
+      def submitted_source
+        value = params[:source]
+        return value if value.is_a?(String) && NewsletterSubscriber.clean_source(value)
+
+        referer = request.referer.to_s
+        URI.parse(referer).path if referer.present?
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def rate_limited
+        render "shiplog/newsletter/rate_limited", status: :too_many_requests
+      end
+    end
+  end
+end

data/app/controllers/shiplog/newsletter/unsubscriptions_controller.rb

@@ -0,0 +1,36 @@
+module Shiplog
+  module Newsletter
+    # The unsubscribe link of every newsletter, for the host's users and Shiplog's subscribers alike: the token is
+    # the encrypted email (Newsletter::Tokens), so Shiplog needs no row for a host user until they unsubscribe.
+    # GET shows a page with a button; POST unsubscribes the address from both lists (Newsletter.unsubscribe,
+    # which keeps a suppression row and calls config.on_newsletter_unsubscribe). The POST is also the RFC 8058
+    # one-click target the List-Unsubscribe-Post header names: the mail provider sends it with the body
+    # "List-Unsubscribe=One-Click" and no CSRF token, so the action checks none; the token in the URL is what
+    # authorises it. Still available while config.newsletter is off: an old email's link must keep working.
+    class UnsubscriptionsController < NewsletterController
+      skip_before_action :require_newsletter
+      before_action :require_newsletter_tables
+      skip_forgery_protection only: :create
+
+      around_action :with_email
+
+      def show
+      end
+
+      def create
+        Newsletter.unsubscribe(@email)
+        render :create
+      end
+
+      private
+
+      def with_email
+        @email = Tokens.email_for(params[:token])
+        return render_invalid_link unless @email
+
+        subscriber = NewsletterSubscriber.find_by_email(@email)
+        I18n.with_locale(Newsletter.i18n_locale(subscriber ? subscriber.locale : I18n.locale)) { yield }
+      end
+    end
+  end
+end

data/app/controllers/shiplog/newsletter_controller.rb

@@ -0,0 +1,34 @@
+module Shiplog
+  # Parent of the newsletter's public pages (subscribe, confirm, preferences, unsubscribe), all under /shiplog/
+  # so a host that constrains the engine's mount to its own paths lets them through. Subscribing and confirming
+  # answer 404 while the newsletter is off; the unsubscribe and preferences pages keep working as long as the
+  # tables exist (a link in an old email must still unsubscribe). None is ever cached: they are personal (a
+  # token in the URL) or carry a fresh CSRF token.
+  #
+  # None of them changes state on a GET: email link scanners prefetch links, so a link in an email opens a page
+  # with a button, and the button POSTs. The one-click unsubscribe (RFC 8058) is the exception by design: the
+  # mail provider POSTs it (see Newsletter::UnsubscriptionsController).
+  class NewsletterController < PublicController
+    helper Shiplog::NewsletterHelper
+
+    before_action :require_newsletter
+    before_action :no_store
+
+    private
+
+    def require_newsletter
+      head :not_found unless Shiplog.newsletter?
+    end
+
+    # For the pages that outlive config.newsletter: the tables must be there.
+    def require_newsletter_tables
+      head :not_found unless Newsletter.available?
+    end
+
+    # The page for a link that does not verify (tampered, expired, used, or a deleted subscriber). A 404 carries
+    # no hint of which.
+    def render_invalid_link
+      render "shiplog/newsletter/invalid", status: :not_found
+    end
+  end
+end

data/app/controllers/shiplog/public_controller.rb

@@ -11,12 +11,18 @@ module Shiplog
     helper Shiplog::PermalinkHelper
     helper Shiplog::StructuredDataHelper
     helper Shiplog::HeadHelper
+    helper Shiplog::NewsletterHelper
     layout -> { Shiplog.config.public_layout }
 
     # Marks the controllers of the public pages, for shiplog_head_tags: checking this instead of the class keeps
     # host pages from autoloading Shiplog::PublicController (and the host's parent controller).
     def shiplog_public_page? = true
 
+    # The entry a permalink or announcement page shows (nil on the other pages), for config.on_changelog_seen and
+    # host layouts: `controller.shiplog_entry&.announcement?` tells an announcement visit apart.
+    def shiplog_entry = @entry
+    helper_method :shiplog_entry
+
     private
 
     # Calls config.on_changelog_seen for a visit to the changelog index or a permalink page. It runs before

data/app/frontend/shiplog/admin.css

@@ -134,7 +134,12 @@
   .shiplog-admin .shiplog-admin-images__controls { display: grid; flex: 1; gap: 0.5rem; min-width: 16rem; }
   .shiplog-admin .shiplog-admin__visually-hidden { border: 0; clip-path: inset(50%); height: 1px; overflow: hidden; position: absolute; white-space: nowrap; width: 1px; }
   .shiplog-admin .shiplog-area-row__count { text-align: right; }
+  .shiplog-admin .shiplog-admin-preview { background: var(--sa-bg); border-radius: 0.5rem; overflow-wrap: anywhere; padding: 0.75rem 1rem; }
+  .shiplog-admin .shiplog-admin-export { display: inline-flex; gap: 0.5rem; margin-left: 0.75rem; }
   .shiplog-admin .shiplog-admin-source { background: var(--sa-bg); overflow-x: auto; padding: 0.75rem; white-space: pre-wrap; word-break: break-word; }
+  .shiplog-admin .shiplog-admin-counts { margin-bottom: 1rem; width: auto; }
+  .shiplog-admin .shiplog-admin-counts__number { text-align: right; }
+  .shiplog-admin .shiplog-admin-newsletter__progress { margin: 0 0 0.5rem; }
 
   .shiplog-admin .shiplog-board { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); }
   .shiplog-admin .shiplog-board__title { font-size: 1.125rem; margin: 0 0 0.5rem; }

data/app/frontend/shiplog/once.js

@@ -0,0 +1,31 @@
+// Forms marked data-shiplog-once (the newsletter's Send, Send test and Retry) submit once: their buttons are
+// disabled and marked busy as soon as the form is submitted, so a double click sends one request. The server is
+// idempotent anyway (delivery rows are claimed atomically); this only spares the admin a confusing second request.
+// Buttons come back when the page is restored from the back/forward cache.
+const SELECTOR = "form[data-shiplog-once]"
+
+document.addEventListener("submit", (event) => {
+  const form = event.target
+  if (!(form instanceof HTMLFormElement) || !form.matches(SELECTOR)) return
+
+  if (form.dataset.shiplogSubmitted === "true") {
+    event.preventDefault()
+    return
+  }
+  form.dataset.shiplogSubmitted = "true"
+  form.setAttribute("aria-busy", "true")
+  // Disabled after the submit event, so the clicked button's name and value are still sent.
+  setTimeout(() => {
+    form.querySelectorAll("button, input[type=submit]").forEach((button) => { button.disabled = true })
+  }, 0)
+})
+
+window.addEventListener("pageshow", (event) => {
+  if (!event.persisted) return
+
+  document.querySelectorAll(SELECTOR).forEach((form) => {
+    delete form.dataset.shiplogSubmitted
+    form.removeAttribute("aria-busy")
+    form.querySelectorAll("button, input[type=submit]").forEach((button) => { button.disabled = false })
+  })
+})

data/app/frontend/shiplog/shiplog.css

@@ -285,6 +285,34 @@
   .shiplog-permalink__back:focus-visible,
   .shiplog-permalink__nav-link:focus-visible { outline: 2px solid var(--sl-accent); outline-offset: 2px; }
 
+  .shiplog-announcement {
+    background: var(--sl-card);
+    border: 1px solid var(--sl-border);
+    border-left: 4px solid var(--sl-accent);
+    border-radius: var(--sl-radius);
+    padding: calc(var(--sl-space) * 1.25);
+  }
+  .shiplog-announcement .shiplog-entry__category { background: var(--sl-accent); border-color: var(--sl-accent); color: #fff; }
+  .shiplog-announcement__title { font-size: 1.5rem; line-height: 1.25; margin: 0.5rem 0 var(--sl-space); }
+  .shiplog-announcement__body { line-height: 1.6; }
+  .shiplog-announcement__body h3,
+  .shiplog-announcement__body h4,
+  .shiplog-announcement__body h5 { line-height: 1.3; margin: calc(var(--sl-space) * 1.5) 0 0.5rem; }
+  .shiplog-announcement__body h3 { font-size: 1.125rem; }
+  .shiplog-announcement__body h4 { font-size: 1rem; }
+  .shiplog-announcement__body p,
+  .shiplog-announcement__body ul,
+  .shiplog-announcement__body ol,
+  .shiplog-announcement__body blockquote { margin: 0.5rem 0; }
+  .shiplog-announcement__body ul,
+  .shiplog-announcement__body ol { padding-left: 1.25rem; }
+  .shiplog-announcement__body a { color: var(--sl-accent); }
+  .shiplog-announcement__body img { border-radius: var(--sl-radius); height: auto; max-width: 100%; }
+  .shiplog-announcement__body blockquote { border-left: 3px solid var(--sl-border); color: var(--sl-muted); margin-left: 0; padding-left: var(--sl-space); }
+  .shiplog-month__announcement { margin: -0.25rem 0 0.75rem; }
+  .shiplog-month__announcement-link { color: var(--sl-accent); font-weight: 600; }
+  .shiplog-month__announcement-link:focus-visible { outline: 2px solid var(--sl-accent); outline-offset: 2px; }
+
   .shiplog-entry__area {
     color: var(--sl-muted);
     font-size: 0.75rem;
@@ -336,6 +364,50 @@
   .shiplog-search__clear { color: var(--sl-accent); margin-left: 0.5rem; }
   .shiplog-search__empty { color: var(--sl-muted); margin: 0; }
 
+  /* Newsletter: the subscribe form on the changelog and announcement pages, and the confirm / preferences /
+     unsubscribe pages (.shiplog-newsletter--page). */
+  .shiplog-newsletter {
+    background: var(--sl-card);
+    border: 1px solid var(--sl-border);
+    border-radius: var(--sl-radius);
+    margin: calc(var(--sl-space) * 2) 0;
+    padding: var(--sl-space) calc(var(--sl-space) * 1.25);
+  }
+  .shiplog-newsletter__title { font-size: 1.125rem; line-height: 1.3; margin: 0 0 0.25rem; }
+  .shiplog-newsletter__hint { color: var(--sl-muted); font-size: 0.875rem; margin: 0 0 0.75rem; }
+  .shiplog-newsletter__form { display: flex; flex-wrap: wrap; gap: 0.5rem; align-items: center; }
+  .shiplog-newsletter__label { font-weight: 500; }
+  .shiplog-newsletter__input {
+    flex: 1 1 14rem;
+    min-width: 0;
+    font: inherit;
+    color: inherit;
+    background: var(--sl-bg);
+    border: 1px solid var(--sl-border);
+    border-radius: var(--sl-radius);
+    padding: 0.4rem 0.75rem;
+  }
+  .shiplog-newsletter__button {
+    font: inherit;
+    color: #fff;
+    background: var(--sl-accent);
+    border: 1px solid var(--sl-accent);
+    border-radius: var(--sl-radius);
+    padding: 0.4rem 1rem;
+    cursor: pointer;
+  }
+  .shiplog-newsletter__button--secondary { color: var(--sl-fg); background: transparent; border-color: var(--sl-border); }
+  .shiplog-newsletter__input:focus-visible,
+  .shiplog-newsletter__button:focus-visible { outline: 2px solid var(--sl-accent); outline-offset: 2px; }
+  .shiplog-newsletter__notice { margin: 0 0 0.75rem; }
+  .shiplog-newsletter__notice--error { color: #cf222e; }
+  .shiplog-newsletter__actions { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-top: var(--sl-space); }
+  .shiplog-newsletter__actions form { margin: 0; }
+  /* The honeypot: out of view for people (never display:none, which some bots detect), labelled for nobody. */
+  .shiplog-newsletter__trap { height: 1px; left: -10000px; overflow: hidden; position: absolute; top: auto; width: 1px; }
+  .shiplog-newsletter--page { margin-top: 0; }
+  .shiplog-newsletter--page p { margin: 0 0 0.75rem; }
+
   @media (max-width: 40rem) {
     .shiplog-page { padding: var(--sl-space) 0.75rem; }
     .shiplog-page__title { font-size: 1.5rem; }

data/app/helpers/shiplog/admin/entries_helper.rb

@@ -9,8 +9,10 @@ module Shiplog
         subject.is_a?(Commit) ? subject.message.lines.drop(1).join.strip : subject.body.to_s
       end
 
+      # A commit's short sha, a period's month, or "owner/name#123".
       def source_reference(subject)
         return subject.sha.first(7) if subject.is_a?(Commit)
+        return subject.title if subject.is_a?(Period)
 
         "#{subject.repository.full_name}##{subject.number}"
       end

data/app/helpers/shiplog/newsletter_helper.rb

@@ -0,0 +1,28 @@
+module Shiplog
+  # The newsletter's subscribe form. The changelog and announcement pages render it while config.newsletter is
+  # on; a host renders it on any page with `helper Shiplog::NewsletterHelper` and `<%= shiplog_newsletter_form %>`
+  # (or `render "shiplog/newsletter/form"` once the helper is included). Nothing is rendered while the newsletter
+  # is off. Uses the engine's own route helpers, or the proxy of the host's mount in host views (see SwitcherHelper).
+  module NewsletterHelper
+    include Shiplog::SwitcherHelper
+
+    # The form (and the bundled stylesheet once per host page, unless config.stylesheet is false). `source` is
+    # recorded with the subscription as the page it was made on; the request's path by default.
+    def shiplog_newsletter_form(source: nil)
+      return "".html_safe unless Shiplog.newsletter?
+
+      stylesheet = if Shiplog.config.stylesheet && !@_shiplog_stylesheet_emitted
+        @_shiplog_stylesheet_emitted = true
+        tag.link(rel: "stylesheet", nonce: content_security_policy_nonce,
+          href: shiplog_routes.frontend_path(version: Shiplog::VERSION, name: "shiplog.css"))
+      end
+      safe_join([ stylesheet, render("shiplog/newsletter/form", source:) ])
+    end
+
+    # The form's action, in the engine's pages and the host's alike.
+    def shiplog_newsletter_subscription_path = shiplog_routes.newsletter_subscription_path
+
+    # The page the subscription is recorded as made on: the given source, else the request's path.
+    def shiplog_newsletter_source(source) = (source.presence || request.path).to_s.first(NewsletterSubscriber::SOURCE_MAX_LENGTH)
+  end
+end

data/app/helpers/shiplog/newsletter_mailer_helper.rb

@@ -0,0 +1,37 @@
+module Shiplog
+  # The inline styles of the newsletter templates: one place for the palette (light colours that email clients
+  # invert sanely in dark mode, no pure black) and the pieces an overriding template can reuse (buttons, cards).
+  module NewsletterMailerHelper
+    PALETTE = {
+      page: "#f3f4f6", card: "#ffffff", text: "#1f2328", muted: "#59636e", border: "#d1d9e0", soft: "#f6f8fa"
+    }.freeze
+    FONT = "-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif".freeze
+    RADIUS = "10px".freeze
+
+    def shiplog_mail_palette = PALETTE
+
+    def shiplog_mail_font = FONT
+
+    # A button: a one-cell table (Outlook ignores padding on links) with the accent as background. `margin` is the
+    # table's CSS margin.
+    def shiplog_mail_button(label, url, accent, margin: "24px 0 0")
+      return if url.blank?
+
+      tag.table(role: "presentation", cellpadding: "0", cellspacing: "0", border: "0", style: "margin:#{margin};") do
+        tag.tr(tag.td(style: "background-color:#{accent};border-radius:6px;") do
+          link_to(label, url, style: "display:inline-block;padding:11px 20px;font-family:#{FONT};font-size:15px;font-weight:600;color:#ffffff;text-decoration:none;")
+        end)
+      end
+    end
+
+    # A highlight's screenshot: full width, rounded top corners, sized from the blob's metadata when known.
+    def shiplog_mail_screenshot(highlight)
+      return unless highlight.image?
+
+      options = { alt: highlight.image_alt, width: 600, border: 0,
+        style: "display:block;width:100%;max-width:600px;height:auto;border:0;border-radius:#{RADIUS} #{RADIUS} 0 0;" }
+      options[:height] = (600.0 * highlight.image_height / highlight.image_width).round if highlight.image_width.to_i.positive? && highlight.image_height.to_i.positive?
+      link_to(image_tag(highlight.image_url, **options), highlight.url, style: "display:block;text-decoration:none;")
+    end
+  end
+end

data/app/helpers/shiplog/permalink_helper.rb

@@ -37,13 +37,30 @@ module Shiplog
       path ? link_to(name, path, html_options) : content_tag(:span, name, html_options.slice(:class))
     end
 
+    # Where a month heading's "Read the summary" link goes: the announcement's page (config.announcements = :page),
+    # or what config.announcement_url returns for it (:external; evaluated in the view with the announcement and
+    # the locale). Nil, so no link, when there is none, it raises or it is not a safe link.
+    def shiplog_announcement_href(announcement)
+      return shiplog_entry_path(announcement) if Shiplog.announcement_pages?
+
+      callable = Shiplog.config.announcement_url
+      return unless Shiplog.config.announcements == :external && callable
+
+      value = callable.is_a?(Proc) ? instance_exec(announcement, I18n.locale, &callable) : callable.call(announcement, I18n.locale)
+      value if Shiplog::Configuration.safe_url?(value)
+    rescue StandardError => error
+      Rails.logger.error("[shiplog] config.announcement_url failed for entry #{announcement.id}: #{error.class}: #{error.message}")
+      nil
+    end
+
     # The id of a month's section on the changelog list.
     def shiplog_month_anchor(date) = "shiplog-month-#{date.strftime("%Y-%m")}"
 
     # The body, on one line and cut for a meta description. Plain text: tag helpers escape it. `escape: false`
     # keeps the cut text raw (not HTML-escaped) for JSON, which escapes it its own way.
     def shiplog_entry_description(entry, escape: true)
-      truncate(entry.display_body.to_s.squish, length: DESCRIPTION_LENGTH, separator: " ", escape:)
+      text = entry.announcement? ? Shiplog::Markdown.to_text(entry.display_body) : entry.display_body.to_s
+      truncate(text.squish, length: DESCRIPTION_LENGTH, separator: " ", escape:)
     end
 
     # The Open Graph meta tags of a permalink page, for `content_for :shiplog_og` (superseded by shiplog_head_tags).
@@ -103,7 +120,8 @@ module Shiplog
         url = shiplog_image_url(image)
         tag.p(tag.img(src: url, alt: entry.image_alt(image), **shiplog_image_size(image))) if url
       end
-      safe_join([ simple_format(h(entry.display_body)), *images ], "\n")
+      text = entry.announcement? ? Shiplog::Markdown.to_html(entry.display_body) : simple_format(h(entry.display_body))
+      safe_join([ text, *images ], "\n")
     end
 
     # An entry's images in order, or none while screenshots are off.

data/app/helpers/shiplog/unseen_helper.rb

@@ -5,5 +5,9 @@ module Shiplog
   module UnseenHelper
     # The number of approved features and changes approved after `since` (all of them while it is nil), at most 99.
     def shiplog_unseen_count(since) = Shiplog.unseen_count(since:)
+
+    # The number of approved monthly announcements approved after `since` (all of them while it is nil), at most 99:
+    # the rare signal for a badge, where shiplog_unseen_count counts every daily entry.
+    def shiplog_unseen_announcements_count(since) = Shiplog.unseen_announcements_count(since:)
   end
 end

data/app/jobs/shiplog/announce_job.rb

@@ -0,0 +1,30 @@
+module Shiplog
+  # Calls config.on_announcement_approved with an approved announcement, and sends the
+  # `announcement_approved.shiplog` notification, once its translations into every configured locale are current
+  # (or cannot be made: no rewriter). Enqueued when an announcement is approved and after each translation of one;
+  # whichever run finds it ready announces it, once per approval (Entry#announce!).
+  #
+  # The hook runs inside the announcement's row lock and transaction: keep it fast (enqueue your own job). A hook
+  # that raises, or a worker that dies mid-hook, leaves the announcement unannounced, and the retry calls it again;
+  # after the last attempt the error is logged and the admin can "Notify now". `force: true` (that button) does not
+  # wait for translations.
+  class AnnounceJob < ApplicationJob
+    ATTEMPTS = 3
+    EVENT = "announcement_approved.shiplog".freeze
+
+    retry_on StandardError, attempts: ATTEMPTS, wait: :polynomially_longer do |job, error|
+      Rails.logger.error("[shiplog] Giving up announcing entry #{job.arguments.first.try(:id)} after #{ATTEMPTS} attempts: #{error.class}: #{error.message}")
+    end
+    discard_on ActiveJob::DeserializationError, ActiveRecord::RecordNotFound
+
+    def perform(entry, force: false)
+      return unless Shiplog.announcements?
+
+      entry.announce!(force:) do
+        ActiveSupport::Notifications.instrument(EVENT, announcement: entry) do
+          Shiplog.config.on_announcement_approved&.call(entry)
+        end
+      end
+    end
+  end
+end

data/app/jobs/shiplog/draft_announcement_job.rb

@@ -0,0 +1,9 @@
+module Shiplog
+  # Drafts the announcement of a month (the previous one by default) and enqueues its rewrite. Schedule it once a
+  # month, early in the month (see the README's Scheduling section); running it again is harmless.
+  class DraftAnnouncementJob < ApplicationJob
+    def perform(month = nil)
+      Announcements.draft(month: month || Date.current.prev_month)
+    end
+  end
+end

data/app/jobs/shiplog/purge_newsletter_job.rb

@@ -0,0 +1,15 @@
+module Shiplog
+  # Housekeeping of the newsletter's tables, to schedule weekly like ScanChangesJob (see the README's Scheduling
+  # section): deletes the subscribers who never confirmed within 30 days (NewsletterSubscriber::PENDING_FOR: an
+  # address typed by someone else, or a confirmation email that never arrived) and the delivery rows older than
+  # 180 days (NewsletterDelivery::RETENTION: the idempotency record of a send long done). Confirmed and
+  # unsubscribed rows are never touched. Returns { subscribers:, deliveries: } counts.
+  class PurgeNewsletterJob < ApplicationJob
+    def perform
+      subscribers = NewsletterSubscriber.purge_pending
+      deliveries = NewsletterDelivery.purge
+      Rails.logger.info("[shiplog] Purged #{subscribers} unconfirmed newsletter #{subscribers == 1 ? "subscriber" : "subscribers"} and #{deliveries} old delivery #{deliveries == 1 ? "row" : "rows"}")
+      { subscribers:, deliveries: }
+    end
+  end
+end