shiplog 0.3.2 → 0.4.0

data/config/admin_routes.rb

@@ -5,6 +5,15 @@ Shiplog::Admin::Engine.routes.draw do
       resource :approval, only: :create
       resource :discard, only: %i[create destroy]
       resource :rewrite, only: :create
+      # An announcement's text as a file to paste elsewhere: ?as=markdown, html or text, in the default locale or
+      # ?export_locale= (not :locale, which a host's locale-switching around_action would read; see translations).
+      get "export", to: "exports#show", as: :export
+      resource :announcement_notification, only: :create
+      # The newsletter of an announcement: the confirmation step with the recipient counts (show), the send
+      # (create), a test to the admin's address, and the retry of failed deliveries.
+      resource :newsletter, only: %i[show create]
+      resource :newsletter_test, only: :create, path: "newsletter/test"
+      resource :newsletter_retry, only: :create, path: "newsletter/retry"
       # The locale segment is :translation_locale, not :locale: a host's around_action that switches the locale
       # from params[:locale] must not read it (a configured translation locale may not be an available one).
       locale = { translation_locale: /[A-Za-z][A-Za-z0-9_-]*/ }
@@ -15,6 +24,9 @@ Shiplog::Admin::Engine.routes.draw do
       end
     end
   end
+  resources :announcements, only: :create
+  # The newsletter's subscribers: counts, a searchable list (?q=), removal, and the CSV export (.csv).
+  resources :newsletter_subscribers, only: %i[index destroy], path: "newsletter"
   resource :area_detection, only: :create, path: "areas/detection"
   resource :area_translation, only: :create, path: "areas/translation"
   resources :areas, only: %i[index update destroy] do

data/config/locales/en.yml

@@ -14,6 +14,7 @@ en:
     categories:
       feature: New
       change: Improved
+      announcement: Monthly update
     empty: Nothing here yet
     date_format: "%-d %B %Y"
     roadmap:
@@ -55,17 +56,161 @@ en:
       nav_label: More changelog entries
       newer: "← Newer: %{title}"
       older: "Older: %{title} →"
+    announcements:
+      read: "Read the %{month} summary"
+      back: "← Back to the changelog"
+      skeleton:
+        features: New
+        also_improved: Also improved
     feed:
       title_with_product: "%{product} changelog"
       link_title: Changelog (Atom)
       subscribe: Subscribe (Atom)
+    newsletter:
+      title: Newsletter
+      product: Product updates
+      back: "← Back to the changelog"
+      form:
+        title: Get the monthly summary by email
+        hint: One email a month, no more. Unsubscribe any time.
+        email_label: Email address
+        email_placeholder: you@example.com
+        submit: Subscribe
+        trap_label: Leave this field empty
+        invalid_email: Enter a valid email address.
+      sent:
+        heading: Check your inbox
+        text: We sent you a link to confirm your subscription. Open it to start receiving the monthly summary. If nothing arrives within a few minutes, look in your spam folder.
+      confirm:
+        heading: Confirm your subscription
+        text: "Click the button to receive the monthly summary at %{email}."
+        button: Confirm
+        done_heading: You're subscribed
+        done_text: "The monthly summary will arrive at %{email}. You can change the language or unsubscribe any time from your preferences."
+      preferences:
+        heading: Your subscription
+        email: Email
+        status: Status
+        statuses:
+          pending: Waiting for confirmation
+          confirmed: Subscribed
+          unsubscribed: Unsubscribed
+        language: Language
+        save: Save
+        saved: Preferences saved.
+        unsubscribe: Unsubscribe
+        unsubscribed: You're unsubscribed.
+        resubscribe: Resubscribe
+        resubscribed: You're subscribed again.
+        delete: Delete my data
+        delete_help: Deleting your data removes your address from our records entirely, including the record that you unsubscribed.
+        deleted_heading: Your data was deleted
+        deleted_text: Your email address is no longer stored. You can subscribe again from the changelog at any time.
+      unsubscribe:
+        heading: Unsubscribe
+        text: "Stop receiving the monthly summary at %{email}?"
+        button: Unsubscribe
+        done_heading: You're unsubscribed
+        done_text: "%{email} will not receive the monthly summary anymore."
+      invalid:
+        heading: This link is not valid
+        text: It may have expired or already been used. Subscribe again from the changelog to get a new one.
+      rate_limited:
+        heading: Too many attempts
+        text: Please try again in an hour.
+      mail:
+        view_in_browser: View in browser
+        changelog_button: See everything that shipped
+        highlight_button: See how it works
+        reason: "You receive this email because you subscribed to the %{product} monthly summary."
+        unsubscribe: Unsubscribe
+        preferences: Preferences
+        confirm_subject: "Confirm your subscription to the %{product} newsletter"
+        confirm_heading: One more step
+        confirm_intro: "Confirm that you want to receive the %{product} monthly summary at %{email}."
+        confirm_button: Confirm my subscription
+        confirm_expiry: "The link works for 7 days. If you did not ask for this, ignore this email: nothing is sent without confirmation."
+        confirm_link_text: "Or copy this link:"
     admin:
+      newsletter:
+        title: Newsletter
+        help: The visitors who subscribed through the changelog's form. Your own users (config.newsletter_recipients) are not listed here.
+        total: Total
+        search: Search
+        search_placeholder: Search by email
+        clear: Clear
+        export: Download CSV
+        remove: Remove
+        removed: "%{email} removed."
+        empty: No subscribers yet.
+        no_match: "No subscriber matches “%{query}”."
+        statuses:
+          pending: Pending
+          confirmed: Confirmed
+          unsubscribed: Unsubscribed
+        columns:
+          email: Email
+          locale: Language
+          status: Status
+          source: Signed up on
+          subscribed_at: Signed up
+          recipients: Recipients
+        heading: Newsletter
+        not_sent: Not sent yet.
+        progress: "%{sent} sent, %{failed} failed, %{pending} pending."
+        stalled:
+          one: "%{count} has been pending for more than an hour (the worker may have died): Retry sends it again."
+          other: "%{count} have been pending for more than an hour (the worker may have died): Retry sends them again."
+        retry: Retry failed
+        retry_queued: Retrying the failed deliveries.
+        send: Send…
+        send_blocked: "Sending is not possible yet: %{reasons}."
+        blockers:
+          not_approved: the announcement is not approved
+          translations: "a translation is missing or stale (%{locales})"
+          from: config.newsletter_from is not set
+          address: config.newsletter_address is not set
+          base_url: config.canonical_url is not set (the links in emails must be absolute)
+        test: "Send a test to %{email}"
+        test_locale: Language
+        test_sent: "Test sent to %{email} (%{language})."
+        test_failed: "The test could not be sent (%{error}). See the log."
+        test_no_email: config.current_admin gives no email address, so no test can be sent.
+        confirm_title: "Send the newsletter: %{title}"
+        recipients: Recipients
+        recipients_none: Nobody to send to yet.
+        recipients_error: "The recipients could not be listed (%{error}). See the log for details."
+        confirm_help: Each recipient receives the email once, in their language. Sending again later only reaches the recipients who have not received it.
+        confirm_resend_help: Recipients who already received it are skipped.
+        confirm_button:
+          one: "Send to %{count} recipient"
+          other: "Send to %{count} recipients"
+        queued: The newsletter is being sent. Refresh in a moment.
+        back: Back to the announcement
+      announcements:
+        draft: "Draft announcement for %{month}"
+        drafted: Announcement draft ready.
+        nothing_to_announce: That month has no approved feature or change to announce yet.
+        publishing: Announcement
+        view_page: View the public page
+        external: Published by your app (config.announcements = :external).
+        announced: "Your app was notified (on_announcement_approved) at %{time}."
+        waiting_for_translations: Your app will be notified once every translation is current.
+        announcing: Notifying your app…
+        not_approved: Approve it to publish it and notify your app.
+        export: "Export:"
+        plain_text: Plain text
+        preview: Preview
+        notify_now: Notify now
+        notify_now_hint: Calls your app's hook now, without waiting for missing translations (English is used for them).
+        notify_queued: Your app will be notified in a moment.
       title: Shiplog admin
       nav:
         drafts: Drafts
         board: Roadmap board
         sync: Sync
         areas: Areas
+        newsletter: Newsletter
       areas:
         title: Product areas
         help: The AI groups entries into areas (at most %{max}) while it rewrites them. Visitors can filter the changelog by area once two areas have published entries.
@@ -126,6 +271,7 @@ en:
         area_gone: no longer exists
         regenerate_warning: Regenerating unpublishes this entry until re-approved.
         source_changed: GitHub text changed since this draft
+        entries_changed: The month's entries changed since this draft
         rewrite_error: Rewrite failed
         not_rewritten: Not rewritten yet
         public_text: Public text
@@ -175,6 +321,7 @@ en:
           roadmap: Roadmap
           feature: Feature
           change: Change
+          announcement: Announcement
         columns:
           entry: Entry
           kind: Kind

data/config/locales/es.yml

@@ -18,6 +18,7 @@ es:
     categories:
       feature: Nuevo
       change: Mejorado
+      announcement: Resumen mensual
     empty: Todavía no hay nada
     date_format: "%-d de %B de %Y"
     roadmap:
@@ -59,17 +60,161 @@ es:
       nav_label: Más cambios
       newer: "← Más reciente: %{title}"
       older: "Anterior: %{title} →"
+    announcements:
+      read: "Leer el resumen de %{month}"
+      back: "← Volver al registro de cambios"
+      skeleton:
+        features: Novedades
+        also_improved: También mejoramos
     feed:
       title_with_product: "Registro de cambios de %{product}"
       link_title: Registro de cambios (Atom)
       subscribe: Suscribirse (Atom)
+    newsletter:
+      title: Boletín
+      product: Novedades del producto
+      back: "← Volver al registro de cambios"
+      form:
+        title: Recibe el resumen mensual por correo
+        hint: Un correo al mes, nada más. Date de baja cuando quieras.
+        email_label: Dirección de correo
+        email_placeholder: tu@ejemplo.com
+        submit: Suscribirme
+        trap_label: Deja este campo vacío
+        invalid_email: Escribe una dirección de correo válida.
+      sent:
+        heading: Revisa tu bandeja de entrada
+        text: Te hemos enviado un enlace para confirmar la suscripción. Ábrelo para empezar a recibir el resumen mensual. Si no llega en unos minutos, mira en la carpeta de spam.
+      confirm:
+        heading: Confirma tu suscripción
+        text: "Pulsa el botón para recibir el resumen mensual en %{email}."
+        button: Confirmar
+        done_heading: Suscripción confirmada
+        done_text: "El resumen mensual llegará a %{email}. Puedes cambiar el idioma o darte de baja cuando quieras desde tus preferencias."
+      preferences:
+        heading: Tu suscripción
+        email: Correo
+        status: Estado
+        statuses:
+          pending: Pendiente de confirmación
+          confirmed: Suscrito
+          unsubscribed: Dado de baja
+        language: Idioma
+        save: Guardar
+        saved: Preferencias guardadas.
+        unsubscribe: Darme de baja
+        unsubscribed: Te has dado de baja.
+        resubscribe: Volver a suscribirme
+        resubscribed: Vuelves a estar suscrito.
+        delete: Borrar mis datos
+        delete_help: Borrar tus datos elimina tu dirección de nuestros registros por completo, incluido el registro de tu baja.
+        deleted_heading: Tus datos se han borrado
+        deleted_text: Tu dirección de correo ya no está guardada. Puedes volver a suscribirte desde el registro de cambios cuando quieras.
+      unsubscribe:
+        heading: Darse de baja
+        text: "¿Dejar de recibir el resumen mensual en %{email}?"
+        button: Darme de baja
+        done_heading: Te has dado de baja
+        done_text: "%{email} ya no recibirá el resumen mensual."
+      invalid:
+        heading: Este enlace no es válido
+        text: Puede que haya caducado o que ya se haya usado. Vuelve a suscribirte desde el registro de cambios para recibir otro.
+      rate_limited:
+        heading: Demasiados intentos
+        text: Inténtalo de nuevo dentro de una hora.
+      mail:
+        view_in_browser: Ver en el navegador
+        changelog_button: Ver todo lo que hemos lanzado
+        highlight_button: Ver cómo funciona
+        reason: "Recibes este correo porque te suscribiste al resumen mensual de %{product}."
+        unsubscribe: Darme de baja
+        preferences: Preferencias
+        confirm_subject: "Confirma tu suscripción al boletín de %{product}"
+        confirm_heading: Un paso más
+        confirm_intro: "Confirma que quieres recibir el resumen mensual de %{product} en %{email}."
+        confirm_button: Confirmar mi suscripción
+        confirm_expiry: "El enlace funciona durante 7 días. Si no has pedido esto, ignora este correo: no se envía nada sin confirmación."
+        confirm_link_text: "O copia este enlace:"
     admin:
+      newsletter:
+        title: Boletín
+        help: Los visitantes que se suscribieron desde el formulario del registro de cambios. Tus propios usuarios (config.newsletter_recipients) no aparecen aquí.
+        total: Total
+        search: Buscar
+        search_placeholder: Buscar por correo
+        clear: Limpiar
+        export: Descargar CSV
+        remove: Eliminar
+        removed: "%{email} eliminado."
+        empty: Todavía no hay suscriptores.
+        no_match: "Ningún suscriptor coincide con “%{query}”."
+        statuses:
+          pending: Pendiente
+          confirmed: Confirmado
+          unsubscribed: Dado de baja
+        columns:
+          email: Correo
+          locale: Idioma
+          status: Estado
+          source: Página de alta
+          subscribed_at: Alta
+          recipients: Destinatarios
+        heading: Boletín
+        not_sent: Todavía no se ha enviado.
+        progress: "%{sent} enviados, %{failed} fallidos, %{pending} pendientes."
+        stalled:
+          one: "%{count} lleva más de una hora pendiente (puede que el worker se haya caído): Reintentar lo envía de nuevo."
+          other: "%{count} llevan más de una hora pendientes (puede que el worker se haya caído): Reintentar los envía de nuevo."
+        retry: Reintentar los fallidos
+        retry_queued: Reintentando los envíos fallidos.
+        send: Enviar…
+        send_blocked: "Todavía no se puede enviar: %{reasons}."
+        blockers:
+          not_approved: el anuncio no está aprobado
+          translations: "falta una traducción o está desactualizada (%{locales})"
+          from: config.newsletter_from no está configurado
+          address: config.newsletter_address no está configurado
+          base_url: config.canonical_url no está configurado (los enlaces de los correos deben ser absolutos)
+        test: "Enviar una prueba a %{email}"
+        test_locale: Idioma
+        test_sent: "Prueba enviada a %{email} (%{language})."
+        test_failed: "No se pudo enviar la prueba (%{error}). Consulta el registro."
+        test_no_email: config.current_admin no devuelve una dirección de correo, así que no se puede enviar ninguna prueba.
+        confirm_title: "Enviar el boletín: %{title}"
+        recipients: Destinatarios
+        recipients_none: Todavía no hay nadie a quien enviarlo.
+        recipients_error: "No se pudo obtener la lista de destinatarios (%{error}). Consulta el registro para más detalles."
+        confirm_help: Cada destinatario recibe el correo una sola vez, en su idioma. Si lo envías de nuevo más tarde, solo llega a quienes no lo han recibido.
+        confirm_resend_help: Se omite a quienes ya lo recibieron.
+        confirm_button:
+          one: "Enviar a %{count} destinatario"
+          other: "Enviar a %{count} destinatarios"
+        queued: El boletín se está enviando. Actualiza la página en un momento.
+        back: Volver al anuncio
+      announcements:
+        draft: "Redactar el anuncio de %{month}"
+        drafted: El borrador del anuncio está listo.
+        nothing_to_announce: Ese mes aún no tiene ninguna función o cambio aprobado que anunciar.
+        publishing: Anuncio
+        view_page: Ver la página pública
+        external: Lo publica tu aplicación (config.announcements = :external).
+        announced: "Se avisó a tu aplicación (on_announcement_approved) el %{time}."
+        waiting_for_translations: Se avisará a tu aplicación cuando todas las traducciones estén al día.
+        announcing: Avisando a tu aplicación…
+        not_approved: Apruébalo para publicarlo y avisar a tu aplicación.
+        export: "Exportar:"
+        plain_text: Texto sin formato
+        preview: Vista previa
+        notify_now: Avisar ahora
+        notify_now_hint: Llama ahora al hook de tu aplicación, sin esperar las traducciones que falten (se usa el inglés).
+        notify_queued: Se avisará a tu aplicación en un momento.
       title: Administración de Shiplog
       nav:
         drafts: Borradores
         board: Tablero de la hoja de ruta
         sync: Sincronización
         areas: Áreas
+        newsletter: Boletín
       areas:
         title: Áreas del producto
         help: La IA agrupa las entradas en áreas (como máximo %{max}) mientras las reescribe. Los visitantes pueden filtrar el registro de cambios por área cuando hay dos áreas con entradas publicadas.
@@ -130,6 +275,7 @@ es:
         area_gone: ya no existe
         regenerate_warning: Al regenerar, esta entrada deja de estar publicada hasta que se apruebe de nuevo.
         source_changed: El texto de GitHub cambió desde este borrador
+        entries_changed: Las entradas del mes cambiaron desde este borrador
         rewrite_error: Falló la reescritura
         not_rewritten: Todavía sin reescribir
         public_text: Texto público
@@ -179,6 +325,7 @@ es:
           roadmap: Hoja de ruta
           feature: Función
           change: Cambio
+          announcement: Anuncio
         columns:
           entry: Entrada
           kind: Tipo

data/config/routes.rb

@@ -7,5 +7,18 @@ Shiplog::Engine.routes.draw do
     format: false, constraints: { slug: /[a-z0-9-]+/ }
   get Shiplog.config.changelog_path, to: "changelogs#show", as: :changelog
   post "shiplog/github/webhook", to: "webhooks#create", as: :github_webhook
+  # The newsletter's pages live under shiplog/ (like the webhook), so a host that constrains the engine's mount to
+  # the changelog, the roadmap and /shiplog/ lets them through. Links from emails open a page with a button
+  # (GET), and the button POSTs: nothing changes state on a GET. A token is URL-safe base64 or base58.
+  token = { token: /[A-Za-z0-9_-]+/ }
+  get "shiplog/newsletter/subscription", to: "newsletter/subscriptions#show", as: :newsletter_subscription
+  post "shiplog/newsletter/subscription", to: "newsletter/subscriptions#create"
+  get "shiplog/newsletter/confirm/:token", to: "newsletter/confirmations#show", as: :newsletter_confirmation, constraints: token, format: false
+  post "shiplog/newsletter/confirm/:token", to: "newsletter/confirmations#create", constraints: token, format: false
+  get "shiplog/newsletter/preferences/:token", to: "newsletter/preferences#show", as: :newsletter_preferences, constraints: token, format: false
+  patch "shiplog/newsletter/preferences/:token", to: "newsletter/preferences#update", constraints: token, format: false
+  delete "shiplog/newsletter/preferences/:token", to: "newsletter/preferences#destroy", constraints: token, format: false
+  get "shiplog/newsletter/unsubscribe/:token", to: "newsletter/unsubscriptions#show", as: :newsletter_unsubscription, constraints: token, format: false
+  post "shiplog/newsletter/unsubscribe/:token", to: "newsletter/unsubscriptions#create", constraints: token, format: false
   get "shiplog/assets/:version/:name", to: "frontends#show", as: :frontend, constraints: { version: /[^\/]+/, name: /[a-z_]+\.(css|js)/ }
 end

data/db/migrate/20261028000001_shiplog_0_4_0.rb

@@ -0,0 +1,19 @@
+# Everything 0.4.0 adds to the schema, one section per feature. Additive and reversible.
+class Shiplog040 < ActiveRecord::Migration[8.1]
+  def change
+    # --- Monthly announcements ---
+    # The subject of an announcement entry: one row per month (starts_on is its first day, ends_on its last), so
+    # Shiplog::Entry keeps its polymorphic subject and its unique (subject, kind) index makes drafting idempotent.
+    create_table :shiplog_periods do |t|
+      t.date :starts_on, null: false
+      t.date :ends_on, null: false
+      t.timestamps
+    end
+    add_index :shiplog_periods, :starts_on, unique: true
+
+    # When config.on_announcement_approved was called for the announcement's current approval: set once it is
+    # approved and every configured locale has a current translation, cleared when it returns to draft, so the
+    # hook runs once per approval.
+    add_column :shiplog_entries, :announced_at, :datetime
+  end
+end

data/db/migrate/20261028000002_shiplog_0_4_0_newsletter.rb

@@ -0,0 +1,44 @@
+# The newsletter's tables (0.4.0, second part). Additive and reversible.
+class Shiplog040Newsletter < ActiveRecord::Migration[8.1]
+  def change
+    # --- Newsletter ---
+    # Visitors who subscribed through Shiplog's form, and the addresses that unsubscribed (a suppression record,
+    # also for the host's own users, who are otherwise never stored). Double opt-in: confirmation_nonce is the
+    # single-use secret of the pending confirmation link, cleared when it is used; confirmed_at is set then;
+    # unsubscribed_at keeps an unsubscribed address suppressed; token reaches the preferences page without an
+    # account (rotated after each change there); source is the page the visitor signed up on (a consent record).
+    # Unique on the lowercased email.
+    create_table :shiplog_newsletter_subscribers do |t|
+      t.string :email, null: false
+      t.string :locale, null: false
+      t.string :token, null: false
+      t.string :confirmation_nonce
+      t.datetime :confirmed_at
+      t.datetime :unsubscribed_at
+      t.string :source
+      t.timestamps
+    end
+    add_index :shiplog_newsletter_subscribers, "lower(email)", unique: true, name: "index_shiplog_newsletter_subscribers_on_lower_email"
+    add_index :shiplog_newsletter_subscribers, :token, unique: true
+    add_index :shiplog_newsletter_subscribers, :confirmation_nonce, unique: true
+    add_index :shiplog_newsletter_subscribers, [ :confirmed_at, :unsubscribed_at ], name: "index_shiplog_newsletter_subscribers_on_status"
+
+    # One row per announcement and recipient ("User/42" for the host's users, "Subscriber/7" for Shiplog's
+    # subscribers), inserted before the email is sent: a retried job or a second click never sends twice.
+    # status is pending (claimed), sent or failed (error says why, without the address, for the admin's "Retry
+    # failed"). No email address is kept here; rows older than 180 days are purged.
+    create_table :shiplog_newsletter_deliveries do |t|
+      t.references :announcement, null: false, foreign_key: { to_table: :shiplog_entries, on_delete: :cascade }, index: false
+      t.string :recipient_key, null: false
+      t.string :locale, null: false
+      t.string :status, null: false, default: "pending"
+      t.datetime :sent_at
+      t.text :error
+      t.timestamps
+    end
+    add_index :shiplog_newsletter_deliveries, [ :announcement_id, :recipient_key ], unique: true, name: "index_shiplog_newsletter_deliveries_on_announcement_and_key"
+    add_index :shiplog_newsletter_deliveries, [ :announcement_id, :status ], name: "index_shiplog_newsletter_deliveries_on_announcement_and_status"
+    add_index :shiplog_newsletter_deliveries, :recipient_key
+    add_index :shiplog_newsletter_deliveries, :created_at
+  end
+end

data/lib/generators/shiplog/install/install_generator.rb

@@ -68,7 +68,20 @@ module Shiplog
         area_link: "rounded-full border border-gray-300 px-3 py-0.5 text-sm hover:border-indigo-500 dark:border-gray-700 [&.shiplog-areas__link--current]:border-indigo-600 [&.shiplog-areas__link--current]:bg-indigo-600 [&.shiplog-areas__link--current]:text-white",
         entry_area: "text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400",
         entry_images: "mt-3 grid w-full gap-3",
-        entry_image: "h-auto max-w-full rounded-lg border border-gray-200 dark:border-gray-800"
+        entry_image: "h-auto max-w-full rounded-lg border border-gray-200 dark:border-gray-800",
+        announcement: "rounded-xl border border-gray-200 border-l-4 border-l-indigo-600 bg-white p-5 dark:border-gray-800 dark:border-l-indigo-500 dark:bg-gray-900",
+        announcement_title: "mt-2 mb-4 text-2xl font-semibold text-gray-900 dark:text-white",
+        announcement_body: "leading-relaxed text-gray-700 dark:text-gray-300 [&_h3]:mt-6 [&_h3]:mb-2 [&_h3]:text-lg [&_h3]:font-semibold [&_h4]:mt-4 [&_h4]:font-semibold [&_ul]:list-disc [&_ul]:pl-5 [&_ol]:list-decimal [&_ol]:pl-5 [&_a]:text-indigo-600 [&_a]:underline dark:[&_a]:text-indigo-400 [&_p]:my-2",
+        month_announcement: "-mt-1 mb-3",
+        month_announcement_link: "text-sm font-semibold text-indigo-600 hover:underline dark:text-indigo-400",
+        newsletter: "my-10 rounded-xl border border-gray-200 bg-gray-50 p-5 dark:border-gray-800 dark:bg-gray-900/50",
+        newsletter_title: "text-lg font-semibold",
+        newsletter_hint: "mt-1 mb-3 text-sm text-gray-500 dark:text-gray-400",
+        newsletter_form: "flex flex-wrap items-center gap-2",
+        newsletter_label: "text-sm font-medium",
+        newsletter_input: "min-w-0 flex-1 rounded-md border border-gray-300 bg-white px-3 py-1.5 text-sm dark:border-gray-700 dark:bg-gray-900",
+        newsletter_button: "rounded-md bg-indigo-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-indigo-500 [&.shiplog-newsletter__button--secondary]:bg-transparent [&.shiplog-newsletter__button--secondary]:text-gray-700 [&.shiplog-newsletter__button--secondary]:ring-1 [&.shiplog-newsletter__button--secondary]:ring-gray-300 dark:[&.shiplog-newsletter__button--secondary]:text-gray-300",
+        newsletter_notice: "mb-3 text-sm [&.shiplog-newsletter__notice--error]:text-red-600"
       }.freeze
 
       def copy_initializer

data/lib/generators/shiplog/install/templates/initializer.rb.tt

@@ -174,6 +174,56 @@ Shiplog.configure do |config|
   # decide which URLs set the locale (e.g. a /es scope). The default locale is dropped from the list.
   # config.locales = []   # e.g. [:es]
 
+  # Monthly announcements: a short summary of what shipped in a month, drafted by config.rewriter from the month's
+  # approved entries and the small changes that got none, and approved in the admin like any entry. Schedule
+  # Shiplog::DraftAnnouncementJob early each month (it drafts the previous month), or use the inbox's
+  # "Draft announcement" buttons. Where it is published:
+  #   :page      (default) Shiplog renders /changelog/2026-10, links it from the month's heading and adds it to the feed
+  #   :external  your app publishes it (on_announcement_approved below); the month heading links to announcement_url
+  #   false      no announcements
+  # config.announcements = :page
+  # config.announcement_url = ->(announcement, locale) { main_app.news_path(announcement.slug) }
+
+  # Called with the announcement once it is approved and translated into every configured locale, once per approval
+  # (also sent as the `announcement_approved.shiplog` notification). The announcement offers display_title(locale),
+  # to_markdown(locale), to_html(locale), to_text(locale) and public_url, to publish it elsewhere or email it.
+  # config.on_announcement_approved = ->(announcement) { NewsletterJob.perform_later(announcement) }
+
+  # Newsletter: the approved announcement emailed, in each recipient's language, to your users who opted in and to
+  # the visitors who subscribed through Shiplog's form (double opt-in, stored in shiplog_newsletter_subscribers).
+  # Sending is an explicit admin action on the announcement's page, once per recipient. Needs newsletter_from,
+  # newsletter_address and canonical_url. Schedule Shiplog::PurgeNewsletterJob weekly (unconfirmed addresses).
+  # config.newsletter = false
+
+  # Your users who opted in: a callable returning objects (or a relation, read in batches) responding to #email,
+  # #locale and #id. Shiplog never stores them. Resolve the locale yourself (the user's, then a default).
+  # config.newsletter_recipients = -> { User.where(newsletter: true) }
+
+  # Your own unsubscribe or settings page for those users, linked in the footer as "Preferences". The one-click
+  # unsubscribe of mail providers always comes to Shiplog, which calls on_newsletter_unsubscribe below.
+  # config.newsletter_unsubscribe_url = ->(user) { Rails.application.routes.url_helpers.settings_url(host: "example.com") }
+
+  # Called with the lowercased email on every unsubscribe (one-click, the footer link, the preferences page), so your
+  # own setting follows: Shiplog suppresses the address itself either way, and skips it at send time whatever your
+  # list says. When a user opts in again in your app, call Shiplog::Newsletter.resubscribe(user.email) to lift the
+  # suppression. Errors are logged, never shown to the visitor.
+  # config.on_newsletter_unsubscribe = ->(email) { User.where("lower(email) = ?", email).update_all(newsletter: false) }
+
+  # The sender (also of the confirmation email) and the postal address in the footer (CAN-SPAM requires one).
+  # config.newsletter_from = "Acme <updates@example.com>"
+  # config.newsletter_address = "Acme Inc., 123 Main Street, Springfield"
+
+  # Branding: the logo (an http(s) URL, shown 140px wide) and the accent colour of buttons and links.
+  # config.newsletter_logo_url = "https://example.com/logo.png"
+  # config.newsletter_accent = "#0969da"
+
+  # Merged into every newsletter message (not the confirmation email): ActionMailer options or headers your
+  # delivery gem reads. With Postmark, a broadcast stream keeps complaints away from your transactional email.
+  # config.newsletter_mailer_options = { message_stream: "broadcast" }
+
+  # How many recipients a run claims and emails at a time (Postmark's batch limit by default).
+  # config.newsletter_batch_size = 500
+
   # Callables above cannot be part of the public pages' ETag. Bump this when the output of a callable you
   # configured changes (a new label, another path) so cached pages are refreshed.
   # config.cache_version = nil

data/lib/shiplog/classes.rb

@@ -58,7 +58,20 @@ module Shiplog
       area_link: "shiplog-areas__link",
       entry_area: "shiplog-entry__area",
       entry_images: "shiplog-entry__images",
-      entry_image: "shiplog-entry__image"
+      entry_image: "shiplog-entry__image",
+      announcement: "shiplog-announcement",
+      announcement_title: "shiplog-announcement__title",
+      announcement_body: "shiplog-announcement__body",
+      month_announcement: "shiplog-month__announcement",
+      month_announcement_link: "shiplog-month__announcement-link",
+      newsletter: "shiplog-newsletter",
+      newsletter_title: "shiplog-newsletter__title",
+      newsletter_hint: "shiplog-newsletter__hint",
+      newsletter_form: "shiplog-newsletter__form",
+      newsletter_label: "shiplog-newsletter__label",
+      newsletter_input: "shiplog-newsletter__input",
+      newsletter_button: "shiplog-newsletter__button",
+      newsletter_notice: "shiplog-newsletter__notice"
     }.freeze
 
     KEYS = BEM.keys.freeze