shiplog 0.3.1 → 0.4.0

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

data/lib/shiplog/configuration.rb

@@ -8,6 +8,7 @@ module Shiplog
       :roadmap_path
 
     ADMIN_CHROMES = %i[standalone hosted].freeze
+    ANNOUNCEMENT_MODES = [ :page, :external, false ].freeze
     # Segments of only dots ("." and "..") are path traversal, not names.
     REPOSITORY_NAME = %r{\A(?!\.+/)[\w.-]+/(?!\.+\z)[\w.-]+\z}
     REPOSITORY_OPTION_KEYS = %i[name changelog gem].freeze
@@ -46,8 +47,9 @@ module Shiplog
     # current), on every visit, and may write: keep it cheap, e.g. write only when the stored time is older than
     # the newest entry. Nil by default. Not part of the ETag: it doesn't change the markup.
     attr_reader :on_changelog_seen
-    # Bump it when the output of a callable you configured changes (extra_pages, repository_labels, feedback_path):
-    # callables cannot be part of the ETag, so this is how cached public pages learn about it.
+    # Bump it when the output of a callable you configured changes (extra_pages, repository_labels, feedback_path,
+    # og_image): callables cannot be part of the ETag, so this is how cached public pages learn about it. Also
+    # bump it after changing the layout's head or a shiplog/head/* partial: ETags don't cover layouts.
     attr_accessor :cache_version
     attr_reader :extra_pages, :repository_labels, :roadmap_shipped_count
     # How many product areas the AI may create (default 8). Past it, entries can only join existing areas.
@@ -58,6 +60,44 @@ module Shiplog
     attr_reader :images, :max_images_per_entry
     LOCALE_FORMAT = /\A[A-Za-z][A-Za-z0-9_-]*\z/
 
+    # Monthly announcements (see Shiplog::Announcements). `announcements` is where they are published:
+    #   :page      (default) Shiplog renders /changelog/2026-10, links it from the changelog's month heading and
+    #              puts it in the Atom feed;
+    #   :external  no Shiplog page: the month heading links to `announcement_url`, and the host publishes the text
+    #              itself (on_announcement_approved);
+    #   false      no announcements at all: nothing is drafted, rendered or announced.
+    attr_reader :announcements
+    # Where an announcement is published when `announcements` is :external: a callable
+    # `->(announcement, locale) { url }` evaluated in the view (instance_exec, so `main_app` route helpers work).
+    # A nil or unsafe result renders no link. Not part of the ETag: bump cache_version when its output changes.
+    attr_reader :announcement_url
+    # Called with the announcement (a Shiplog::Entry) once it is approved and every configured locale has a current
+    # translation, from Shiplog::AnnounceJob. Once per approval: an announcement regenerated and approved again
+    # is announced again. An `announcement_approved.shiplog` ActiveSupport notification is sent at the same time.
+    attr_reader :on_announcement_approved
+
+    # The newsletter (see Shiplog::Newsletter): the approved announcement emailed to the host's users who opted in
+    # and to the visitors who subscribed through Shiplog's form. Off by default, and nothing without announcements.
+    attr_reader :newsletter
+    # A callable returning the host's recipients, each responding to #email, #locale and #id (an Active Record
+    # relation is read in batches with find_each). Shiplog never stores them.
+    attr_reader :newsletter_recipients
+    # `->(recipient) { url }`: the host's own unsubscribe or settings page, linked in the footer for its users. The
+    # one-click unsubscribe (List-Unsubscribe-Post) always goes through Shiplog's endpoint, which calls
+    # on_newsletter_unsubscribe. Without it the footer links Shiplog's unsubscribe page.
+    attr_reader :newsletter_unsubscribe_url
+    # `->(email) { ... }`, called on every unsubscribe (one-click, the footer link or the preferences page), so the
+    # host turns its own user's setting off. Errors are logged, never shown to the visitor.
+    attr_reader :on_newsletter_unsubscribe
+    # The sender, e.g. "Acme <updates@acme.com>" (also used by the confirmation email); the postal address the
+    # footer carries (CAN-SPAM requires one); the logo (an http(s) URL) and the accent colour ("#rrggbb") of the
+    # email; extra ActionMailer options for every newsletter message, e.g. { message_stream: "broadcast" } for a
+    # Postmark broadcast stream; how many recipients a job claims at a time (default 500).
+    attr_reader :newsletter_from, :newsletter_address, :newsletter_logo_url, :newsletter_accent,
+      :newsletter_mailer_options, :newsletter_batch_size
+    ACCENT_FORMAT = /\A#(?:\h{3}|\h{6})\z/
+    MAX_NEWSLETTER_BATCH_SIZE = 10_000
+
     EXTRA_PAGE_KEYS = %i[label path].freeze
 
     # A path (not "//host", "/\host" or "/ x", which browsers read as other targets), an http(s) URL or mailto:.
@@ -77,7 +117,8 @@ module Shiplog
         stylesheet, roadmap_shipped_count, cache_version, product_name, canonical_url,
         extra_pages.map { |page| [ stable.(page[:label]), stable.(page[:path]) ] },
         repository_labels.sort_by { |name, _| name.to_s }.map { |name, label| [ name, stable.(label) ] },
-        stable.(feedback_path), changelog_search, images, max_images_per_entry, locales, structured_data, stable.(og_image)
+        stable.(feedback_path), changelog_search, images, max_images_per_entry, locales, structured_data, stable.(og_image),
+        announcements.to_s, stable.(announcement_url), newsletter
       ]
       Digest::SHA256.hexdigest(JSON.generate(data))
     end
@@ -168,11 +209,90 @@ module Shiplog
       @og_image = value
     end
 
+    def announcements=(value)
+      mode = value.is_a?(String) ? value.to_sym : value
+      unless ANNOUNCEMENT_MODES.include?(mode)
+        raise ArgumentError, "announcements must be :page, :external or false, got #{value.inspect}"
+      end
+      @announcements = mode
+    end
+
+    def announcement_url=(value)
+      raise ArgumentError, "announcement_url must be nil or a callable like ->(announcement, locale) { url }, got #{value.inspect}" unless value.nil? || value.respond_to?(:call)
+      @announcement_url = value
+    end
+
+    def on_announcement_approved=(value)
+      raise ArgumentError, "on_announcement_approved must be nil or a callable like ->(announcement) { ... }, got #{value.inspect}" unless value.nil? || value.respond_to?(:call)
+      @on_announcement_approved = value
+    end
+
     def on_changelog_seen=(value)
       raise ArgumentError, "on_changelog_seen must be nil or a callable, got #{value.inspect}" unless value.nil? || value.respond_to?(:call)
       @on_changelog_seen = value
     end
 
+    def newsletter=(value)
+      raise ArgumentError, "newsletter must be true or false, got #{value.inspect}" unless [ true, false ].include?(value)
+      @newsletter = value
+    end
+
+    def newsletter_recipients=(value)
+      raise ArgumentError, "newsletter_recipients must be nil or a callable like -> { User.where(newsletter: true) }, got #{value.inspect}" unless value.nil? || value.respond_to?(:call)
+      @newsletter_recipients = value
+    end
+
+    def newsletter_unsubscribe_url=(value)
+      raise ArgumentError, "newsletter_unsubscribe_url must be nil or a callable like ->(recipient) { url }, got #{value.inspect}" unless value.nil? || value.respond_to?(:call)
+      @newsletter_unsubscribe_url = value
+    end
+
+    def on_newsletter_unsubscribe=(value)
+      raise ArgumentError, "on_newsletter_unsubscribe must be nil or a callable like ->(email) { ... }, got #{value.inspect}" unless value.nil? || value.respond_to?(:call)
+      @on_newsletter_unsubscribe = value
+    end
+
+    def newsletter_from=(value)
+      @newsletter_from = optional_string!(:newsletter_from, value, 'like "Acme <updates@acme.com>"')
+    end
+
+    def newsletter_address=(value)
+      @newsletter_address = optional_string!(:newsletter_address, value, "(the sender's postal address)")
+    end
+
+    def newsletter_logo_url=(value)
+      url = optional_string!(:newsletter_logo_url, value, "with an http(s) URL")
+      raise ArgumentError, "newsletter_logo_url must be an http(s) URL, got #{value.inspect}" if url && !url.match?(%r{\Ahttps?://\S+\z}i)
+      @newsletter_logo_url = url
+    end
+
+    def newsletter_accent=(value)
+      colour = optional_string!(:newsletter_accent, value, 'like "#0969da"')
+      raise ArgumentError, "newsletter_accent must be a hex colour like \"#0969da\", got #{value.inspect}" if colour && !ACCENT_FORMAT.match?(colour)
+      @newsletter_accent = colour&.downcase
+    end
+
+    # Merged into every newsletter message's `mail(...)` call: ActionMailer options (delivery_method,
+    # delivery_method_options) or headers your delivery gem reads (Postmark's message_stream). Keys that would
+    # change who receives the message or what it says are refused.
+    RESERVED_MAILER_OPTIONS = %i[to cc bcc from reply_to sender return_path subject body template_name template_path parts_order content_type charset mime_version date].freeze
+
+    def newsletter_mailer_options=(value)
+      options = value.nil? ? {} : value
+      raise ArgumentError, "newsletter_mailer_options must be a Hash like { message_stream: \"broadcast\" }, got #{value.inspect}" unless options.is_a?(Hash)
+      options = options.transform_keys { |key| key.to_s.to_sym }
+      reserved = options.keys & RESERVED_MAILER_OPTIONS
+      raise ArgumentError, "newsletter_mailer_options cannot set #{reserved.map(&:inspect).join(", ")}: the recipient, sender and content of a newsletter are Shiplog's" if reserved.any?
+      @newsletter_mailer_options = options.freeze
+    end
+
+    def newsletter_batch_size=(value)
+      unless value.is_a?(Integer) && value.between?(1, MAX_NEWSLETTER_BATCH_SIZE)
+        raise ArgumentError, "newsletter_batch_size must be an Integer between 1 and #{MAX_NEWSLETTER_BATCH_SIZE}, got #{value.inspect}"
+      end
+      @newsletter_batch_size = value
+    end
+
     # :standalone (default) wraps the admin in Shiplog's own page chrome; :hosted renders it inside the
     # layout of config.admin_layout (compact sub-nav, no page chrome of its own).
     def admin_chrome=(value)
@@ -244,6 +364,10 @@ module Shiplog
       @images = true
       @max_images_per_entry = 4
       @locales = [].freeze
+      @announcements = :page
+      @newsletter = false
+      @newsletter_mailer_options = {}.freeze
+      @newsletter_batch_size = 500
     end
 
     def resolved_github_token
@@ -282,6 +406,14 @@ module Shiplog
 
     private
 
+    # Nil (also for a blank String) or a stripped non-empty String; anything else raises.
+    def optional_string!(setting, value, hint)
+      return if value.nil? || (value.is_a?(String) && value.strip.empty?)
+      raise ArgumentError, "#{setting} must be nil or a String #{hint}, got #{value.inspect}" unless value.is_a?(String)
+
+      value.strip
+    end
+
     def normalize_canonical_url(value)
       return if value.nil? || (value.is_a?(String) && value.strip.empty?)
       raise ArgumentError, "canonical_url must be a String like \"https://example.com\", got #{value.inspect}" unless value.is_a?(String)

data/lib/shiplog/engine.rb

@@ -9,5 +9,7 @@ module Shiplog
 
     # Once per boot, after the host's initializers have set config.images: say why screenshots are off.
     config.after_initialize { Shiplog.log_images_status }
+    # And why the newsletter, when on, cannot be sent yet.
+    config.after_initialize { Shiplog.log_newsletter_status }
   end
 end

data/{app/helpers → lib}/shiplog/head_tags_helper.rb

@@ -1,22 +1,32 @@
 module Shiplog
+  # Constants of shiplog_head_tags. Not included anywhere, so views of the host cannot see them.
+  module HeadTags
+    EXCEPT_KEYS = %i[description canonical robots open_graph twitter feed structured_data].freeze
+  end
+
   # The one helper added to every view of the host (like a pagination gem's `paginate`), so a layout shared
   # with the host's own pages can call `shiplog_head_tags`. The rest lives in Shiplog::HeadHelper, which only
   # the engine's controllers include.
+  #
+  # This file is required by lib/shiplog.rb rather than autoloaded: the engine includes the module into
+  # ActionView::Base from an on_load hook, which can run during boot before the autoloaders are set up, and
+  # ActionView::Base never reloads, so the module must not either.
   module HeadTagsHelper
-    EXCEPT_KEYS = %i[description canonical robots open_graph twitter feed structured_data].freeze
-
     # The head tags of the current Shiplog page; an empty string on any other page. `except:` leaves groups
     # out, for tags your layout already writes: :description, :canonical, :robots, :open_graph, :twitter,
     # :feed, :structured_data. An unknown key raises ArgumentError.
     #
+    # Call it in the layout, not inside a component (ViewComponent, Phlex): there it gives an empty string.
     # Use it OR the older `content_for :shiplog_*` blocks in a layout, not both: both would emit the tags twice.
     def shiplog_head_tags(except: [])
       keys = Array(except).map { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
-      unknown = keys - EXCEPT_KEYS
+      unknown = keys - HeadTags::EXCEPT_KEYS
       if unknown.any?
-        raise ArgumentError, "Unknown shiplog_head_tags except: key(s) #{unknown.map(&:inspect).join(", ")}. Valid keys: #{EXCEPT_KEYS.map(&:inspect).join(", ")}"
+        raise ArgumentError, "Unknown shiplog_head_tags except: key(s) #{unknown.map(&:inspect).join(", ")}. Valid keys: #{HeadTags::EXCEPT_KEYS.map(&:inspect).join(", ")}"
       end
-      return "".html_safe unless controller.is_a?(Shiplog::PublicController)
+      # A marker, not is_a?(Shiplog::PublicController): that would autoload the controller (and the host's
+      # parent controller) on every host page. Views that don't have the engine's helper (components) skip too.
+      return "".html_safe unless controller.respond_to?(:shiplog_public_page?) && respond_to?(:shiplog_render_head_tags, true)
 
       shiplog_render_head_tags(keys)
     end

data/lib/shiplog/previews/shiplog/newsletter_mailer_preview.rb

@@ -0,0 +1,77 @@
+module Shiplog
+  # Previews of the newsletter's emails, for hosts iterating on the design locally. Add the directory to your
+  # preview paths (config/environments/development.rb):
+  #
+  #   config.action_mailer.preview_paths << Shiplog::Engine.root.join("lib/shiplog/previews").to_s
+  #
+  # then open /rails/mailers/shiplog/newsletter_mailer. The announcement is the newest approved one (with the
+  # month's real feature highlights), or a sample with sample highlights when there is none (no database rows
+  # needed); ?locale=es previews a configured locale.
+  class NewsletterMailerPreview < ActionMailer::Preview
+    SAMPLE_BODY = <<~MARKDOWN.freeze
+      This month we made imports faster and added a dark theme. Here is what shipped.
+
+      ## Highlights
+
+      ### Dark mode
+
+      Switch to a dark theme from your settings. Easier on the eyes at night.
+
+      ### Faster imports
+
+      Spreadsheets with thousands of rows now import in seconds.
+
+      ## Also improved
+
+      ### Billing
+
+      - Invoices show the tax breakdown.
+      - Refunds appear on the next statement.
+
+      ### Exports
+
+      - CSV files keep leading zeros.
+    MARKDOWN
+
+    SAMPLE_HIGHLIGHTS = [
+      { title: "Dark mode", summary: "Switch to a dark theme from your settings, easier on the eyes at night.", slug: "dark-mode",
+        image_url: "https://placehold.co/1200x700/png?text=Dark+mode", image_width: 1200, image_height: 700 },
+      { title: "Faster imports", summary: "Spreadsheets with thousands of rows now import in seconds.", slug: "faster-imports",
+        image_url: "https://placehold.co/1200x700/png?text=Faster+imports", image_width: 1200, image_height: 700 },
+      { title: "Shared views", summary: "Save a filtered view and share it with your team.", slug: "shared-views", image_url: nil }
+    ].freeze
+
+    def announcement
+      entry = Entry.published_announcements.order(released_on: :desc).first
+      locale = (params["locale"] || params[:locale]).presence || I18n.default_locale
+      email = "preview@example.com"
+      content = entry ? nil : Newsletter::Content.new(sample_announcement, locale, highlights: sample_highlights)
+      NewsletterMailer.announcement(entry || content.entry, email, locale:, content:, unsubscribe_url: Newsletter.unsubscribe_url(email),
+        preferences_url: Newsletter.preferences_url(sample_subscriber))
+    end
+
+    def confirmation
+      NewsletterMailer.confirmation(sample_subscriber)
+    end
+
+    private
+
+    def sample_announcement
+      month = Date.current.prev_month.beginning_of_month
+      Entry.new(kind: "announcement", status: "approved", title: Period.month_name(month), body: SAMPLE_BODY,
+        released_on: month.end_of_month, slug: month.strftime("%Y-%m"), subject: Period.new(starts_on: month, ends_on: month.end_of_month))
+    end
+
+    # Three cards, two with a (placeholder) screenshot, linking to sample permalinks under the email's origin.
+    def sample_highlights
+      SAMPLE_HIGHLIGHTS.map do |sample|
+        Newsletter::Content::Highlight.new(title: sample[:title], summary: sample[:summary], url: Newsletter.absolute_url(PublicLinks.path(:changelog_entry_path, sample[:slug])),
+          image_url: sample[:image_url], image_alt: sample[:title], image_width: sample[:image_width], image_height: sample[:image_height])
+      end
+    end
+
+    def sample_subscriber
+      NewsletterSubscriber.new(email: "preview@example.com", locale: I18n.default_locale.to_s, token: "preview-token", confirmation_nonce: "preview-nonce")
+    end
+  end
+end

data/lib/shiplog/version.rb

@@ -1,3 +1,3 @@
 module Shiplog
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/shiplog.rb

@@ -4,6 +4,7 @@ require "shiplog/configuration"
 require "shiplog/github/errors"
 require "shiplog/github/queries"
 require "shiplog/github/client"
+require "shiplog/head_tags_helper"
 require "shiplog/engine"
 require "shiplog/admin/engine"
 
@@ -17,6 +18,38 @@ module Shiplog
     # at 99. Counted on approved_at (when the entry was approved), not released_on (the list's order). The host supplies the timestamp (Shiplog doesn't know its users): see config.on_changelog_seen.
     def unseen_count(since: nil) = Entry.unseen_count(since:)
 
+    # The number of approved monthly announcements approved after `since` (all of them while it is nil), capped
+    # at 99: the rare "what's new" signal, where unseen_count counts every daily entry. 0 while announcements are off.
+    def unseen_announcements_count(since: nil) = announcements? ? Entry.unseen_announcements_count(since:) : 0
+
+    # Whether monthly announcements are on (config.announcements is :page or :external).
+    def announcements? = config.announcements != false
+
+    # Whether Shiplog renders announcement pages (config.announcements is :page).
+    def announcement_pages? = config.announcements == :page
+
+    # Whether the newsletter is on: config.newsletter, and announcements (there is nothing else to send).
+    def newsletter? = config.newsletter && announcements?
+
+    # Logged once at boot (see Shiplog::Engine), while the newsletter is on: what keeps it from sending, a
+    # recipients callable without the unsubscribe hook (unsubscribes would not reach the host's list), and a
+    # cache that counts nothing (the subscribe form's rate limits are then off).
+    def log_newsletter_status
+      return unless newsletter?
+
+      missing = []
+      missing << "newsletter_from" if Newsletter.from.blank?
+      missing << "newsletter_address" if config.newsletter_address.blank?
+      missing << "canonical_url (or action_mailer.default_url_options)" if Newsletter.base_url.blank?
+      Rails.logger&.warn("[shiplog] config.newsletter is on, but the newsletter cannot be sent until these are set: #{missing.join(", ")}.") if missing.any?
+      if config.newsletter_recipients && config.on_newsletter_unsubscribe.nil?
+        Rails.logger&.warn("[shiplog] config.newsletter_recipients is set but config.on_newsletter_unsubscribe is not: Shiplog suppresses an address that unsubscribes, but your own list will not know.")
+      end
+      if Rails.cache.is_a?(ActiveSupport::Cache::NullStore)
+        Rails.logger&.warn("[shiplog] Rails.cache is a null store, so the newsletter's subscribe form is not rate limited. Configure a cache store.")
+      end
+    end
+
     ACTIVE_STORAGE_TABLES = %w[active_storage_attachments active_storage_blobs].freeze
 
     # Whether the host loaded Active Storage (its engine and the model macros). The declaration on Entry needs

data/lib/tasks/shiplog.rake

@@ -8,6 +8,28 @@ unless Rake::Task.task_defined?("shiplog:backfill_slugs")
       puts "Shiplog: gave #{count} #{count == 1 ? "entry" : "entries"} a slug."
     end
 
+    desc "Draft the announcement of a month (MONTH=2026-10; the previous month by default) and queue its rewrite"
+    task draft_announcement: :environment do
+      month = ENV["MONTH"].present? ? Date.strptime(ENV["MONTH"], "%Y-%m") : Date.current.prev_month
+      entry = Shiplog::Announcements.draft(month:)
+      label = month.strftime("%Y-%m")
+      if entry
+        puts "Shiplog: drafted the #{label} announcement (entry #{entry.id})."
+      elsif !Shiplog.announcements?
+        puts "Shiplog: config.announcements is false, nothing drafted."
+      else
+        puts "Shiplog: nothing drafted for #{label}: it has an announcement already, or no approved feature or change."
+      end
+    rescue Date::Error
+      abort "Shiplog: MONTH must look like 2026-10, got #{ENV["MONTH"].inspect}."
+    end
+
+    desc "Delete the newsletter subscribers who never confirmed within 30 days and the delivery rows older than 180 days (what Shiplog::PurgeNewsletterJob does)"
+    task purge_newsletter: :environment do
+      counts = Shiplog::PurgeNewsletterJob.perform_now
+      puts "Shiplog: purged #{counts[:subscribers]} unconfirmed newsletter #{counts[:subscribers] == 1 ? "subscriber" : "subscribers"} and #{counts[:deliveries]} old delivery #{counts[:deliveries] == 1 ? "row" : "rows"}."
+    end
+
     desc "Translate approved entries and area names that have no current translation into config.locales (entries approved before 0.3.0 get none). BATCH_SIZE=100"
     task translate_approved: :environment do
       if Shiplog.config.locales.empty?