shiplog 0.3.1 → 0.4.0

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).
@@ -55,15 +72,16 @@ module Shiplog
       safe_join(tags.compact_blank.map { |property, content| tag.meta(property:, content:) }, "\n")
     end
 
-    # The absolute URL of the image to show when the page is shared, or nil: the entry's first screenshot, else
+    # The absolute URL of the image to show when the page is shared, or nil: the entry's first screenshot with a URL, else
     # what config.og_image returns for it. Computed once per entry per render, so a failing callable is logged
     # once for a page.
     def shiplog_entry_og_image(entry)
       @shiplog_og_images ||= {}.compare_by_identity
       return @shiplog_og_images[entry] if @shiplog_og_images.key?(entry)
 
-      image = shiplog_images(entry).first
-      @shiplog_og_images[entry] = (shiplog_image_url(image) if image) || shiplog_configured_og_image(entry)
+      # Same rule as the JSON-LD Article image: screenshots whose URL can't be built are skipped.
+      screenshot = shiplog_images(entry).lazy.filter_map { |image| shiplog_image_url(image) }.first
+      @shiplog_og_images[entry] = screenshot || shiplog_configured_og_image(entry)
     end
 
     # What config.og_image gives for an entry (called in the view with the entry and the locale), as an absolute
@@ -102,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

data/app/jobs/shiplog/send_newsletter_job.rb

@@ -0,0 +1,64 @@
+module Shiplog
+  # Emails an approved announcement to every recipient (Newsletter::Recipients: the host's users, then the
+  # confirmed subscribers, minus the unsubscribed and the duplicates), once per recipient. For each chunk of
+  # NewsletterDelivery::CLAIM_SIZE it inserts the delivery rows first (one statement, skipping the rows that
+  # exist) and emails only the recipients it inserted, touching each row right before its send, so a retried
+  # job, a second click on Send or two workers never send twice: at most once per recipient. A failed delivery
+  # is recorded on its row (never raised: the chunk goes on) for the admin's "Retry failed", which runs the job
+  # with `retry_failed: true`: the failed and stalled rows are reclaimed in one statement, the ones reclaimed by
+  # this run are sent again, and the ones whose recipient is gone end as failed with the reason.
+  #
+  # The announcement's Markdown is rendered once per locale (Newsletter::Content); each message is then built with
+  # the recipient's own links. The job stops before anything is sent when the newsletter is off or the
+  # announcement cannot be sent (Newsletter.blockers: not approved, missing translations, no sender...).
+  class SendNewsletterJob < ApplicationJob
+    discard_on ActiveJob::DeserializationError, ActiveRecord::RecordNotFound
+
+    def perform(entry, retry_failed: false)
+      return log_skip(entry, "the newsletter is off") unless Newsletter.enabled?
+
+      blockers = Newsletter.blockers(entry)
+      return log_skip(entry, "it cannot be sent: #{blockers.join(", ")}") if blockers.any?
+
+      reclaimed = retry_failed ? NewsletterDelivery.reclaim(entry).to_set : Set.new
+      contents = Hash.new { |hash, locale| hash[locale] = Newsletter::Content.new(entry, locale) }
+      sent = 0
+      Newsletter::Recipients.new.each_batch do |batch|
+        batch.each_slice(NewsletterDelivery::CLAIM_SIZE) do |chunk|
+          claimed = NewsletterDelivery.claim(entry, chunk).to_set
+          chunk.each do |recipient|
+            next unless claimed.include?(recipient.key) || reclaimed.delete?(recipient.key)
+
+            sent += 1 if deliver(entry, recipient, contents[recipient.locale])
+          end
+        end
+      end
+      NewsletterDelivery.mark_missing(entry, reclaimed) # reclaimed, but no longer a recipient
+      Rails.logger.info("[shiplog] Newsletter of entry #{entry.id}: #{sent} emails sent in this run")
+    end
+
+    private
+
+    # Sends one email and records the outcome on the delivery row. True when it was sent.
+    def deliver(entry, recipient, content)
+      NewsletterDelivery.mark_sending(entry, recipient.key)
+      NewsletterMailer.announcement(entry, recipient.email, locale: recipient.locale, content:,
+        unsubscribe_url: Newsletter.unsubscribe_url(recipient.email), preferences_url: preferences_url(recipient)).deliver_now
+      NewsletterDelivery.mark_sent(entry, recipient.key)
+      true
+    rescue StandardError => error
+      NewsletterDelivery.mark_failed(entry, recipient.key, error)
+      Rails.logger.error("[shiplog] Newsletter of entry #{entry.id} to #{recipient.key} failed: #{error.class}: #{NewsletterDelivery.scrub(error.message)}")
+      false
+    end
+
+    # A subscriber's preferences page; a host user's own page when config.newsletter_unsubscribe_url gives one.
+    def preferences_url(recipient)
+      recipient.subscriber? ? Newsletter.preferences_url(recipient.record) : Newsletter.host_unsubscribe_url(recipient.record)
+    end
+
+    def log_skip(entry, reason)
+      Rails.logger.info("[shiplog] Newsletter of entry #{entry.id} not sent: #{reason}")
+    end
+  end
+end

data/app/jobs/shiplog/translate_entry_job.rb

@@ -17,6 +17,8 @@ module Shiplog
 
     def perform(entry, locale, force: false)
       Translator.new(entry, locale).call(force:)
+      # An approved announcement is announced once all its translations are current: this may have been the last.
+      AnnounceJob.perform_later(entry) if entry.announcement?
     rescue StandardError => error
       Rails.logger.error("[shiplog] Translating entry #{entry.id} into #{locale} failed (attempt #{executions} of #{ATTEMPTS}): #{error.class}: #{error.message}")
       raise

data/app/mailers/shiplog/newsletter_mailer.rb

@@ -0,0 +1,51 @@
+module Shiplog
+  # The newsletter's emails: an announcement to one recipient, and the confirmation of a visitor's subscription.
+  # Both have an HTML part (one 600px table column, styles inline, see app/views/shiplog/newsletter_mailer) and a
+  # text part, in the recipient's language (the chrome from Shiplog's I18n keys, the announcement's text from its
+  # translation). Hosts override the templates like any engine view. The sender is config.newsletter_from.
+  class NewsletterMailer < ActionMailer::Base
+    helper Shiplog::NewsletterMailerHelper
+
+    default from: -> { sender! }
+
+    # The announcement for `email` in `locale`. `unsubscribe_url` is the one-click target (the List-Unsubscribe
+    # headers Gmail and Yahoo require; Newsletter.unsubscribe_url for the address when not given, so a queued test
+    # send carries no token), `preferences_url` the page the footer's "Preferences" opens (a subscriber's page, or
+    # the host's own for its users; nil shows the unsubscribe page instead). `content` is the locale's rendered
+    # Content when the caller has it (SendNewsletterJob renders once per locale). config.newsletter_mailer_options
+    # are merged into the message (e.g. Postmark's message_stream); they cannot change the recipient or the subject.
+    def announcement(entry, email, locale:, unsubscribe_url: nil, preferences_url: nil, content: nil)
+      @content = content || Newsletter::Content.new(entry, locale)
+      @unsubscribe_url = unsubscribe_url || Newsletter.unsubscribe_url(email)
+      @preferences_url = preferences_url || @unsubscribe_url
+      headers["List-Unsubscribe"] = "<#{@unsubscribe_url}>"
+      headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click"
+      headers["Precedence"] = "bulk"
+      I18n.with_locale(Newsletter.i18n_locale(@content.locale)) do
+        mail(**Shiplog.config.newsletter_mailer_options, to: email, subject: @content.subject)
+      end
+    end
+
+    # The double opt-in email: a single-use link (valid 7 days) the subscriber must open, in the locale of the
+    # page they subscribed on. `subscriber` is a NewsletterSubscriber, or its id when queued (deliver_later): a
+    # row deleted or confirmed in the meantime sends nothing, quietly. Transactional: no mailer options, no
+    # List-Unsubscribe.
+    def confirmation(subscriber)
+      @subscriber = subscriber.is_a?(NewsletterSubscriber) ? subscriber : NewsletterSubscriber.find_by(id: subscriber)
+      @confirmation_url = @subscriber && Newsletter.confirmation_url(@subscriber)
+      return unless @confirmation_url
+
+      @product_name = Newsletter.product_name
+      I18n.with_locale(Newsletter.i18n_locale(@subscriber.locale)) do
+        mail(to: @subscriber.email, subject: t("shiplog.newsletter.mail.confirm_subject", product: Newsletter.product_name))
+      end
+    end
+
+    private
+
+    # The From address, or a clear error when none is configured (the job records it on the delivery row).
+    def sender!
+      Newsletter.from or raise ArgumentError, "[shiplog] config.newsletter_from is not set, so no newsletter email can be sent"
+    end
+  end
+end

data/app/models/shiplog/announcements.rb

@@ -0,0 +1,34 @@
+module Shiplog
+  # Monthly announcements: a short, AI-drafted summary of what shipped in a month, approved by an admin like every
+  # other entry (kind "announcement", subject a Shiplog::Period). Where it is published is config.announcements.
+  module Announcements
+    # The slug used when a feature or change approved before 0.4.0 already took the month's own ("2026-10").
+    FALLBACK_SUFFIX = "-update".freeze
+
+    # Drafts the announcement of the month containing `month` and enqueues its rewrite. Returns the new draft, or
+    # nil when announcements are off, the month has no approved feature or change (nothing to announce), or it
+    # has an announcement already (whatever its status).
+    def self.draft(month:)
+      return unless Shiplog.announcements?
+
+      starts_on = month.to_date.beginning_of_month
+      return unless Period.changelog_entries_between(starts_on..starts_on.end_of_month).exists?
+
+      period = Period.month(starts_on)
+      Drafter.draft(period, "announcement", released_on: period.ends_on, slug: slug_for(period))
+    end
+
+    # The months an admin can draft from the admin: the current one (so far) and the previous one.
+    def self.draftable_months(today = Date.current) = [ today.beginning_of_month, today.prev_month.beginning_of_month ]
+
+    # "2026-10", or when an older entry already has that slug "2026-10-update", then "2026-10-update-2", ...
+    def self.slug_for(period)
+      month = period.starts_on.strftime("%Y-%m")
+      candidates = Enumerator.new do |yielder|
+        yielder << month << "#{month}#{FALLBACK_SUFFIX}"
+        (2..).each { |suffix| yielder << "#{month}#{FALLBACK_SUFFIX}-#{suffix}" }
+      end
+      candidates.find { |slug| !Entry.where(slug:).where.not(subject: period).exists? }
+    end
+  end
+end

data/app/models/shiplog/area_detector.rb

@@ -99,9 +99,10 @@ module Shiplog
       end
 
       # Entries that may still get an area: drafts and approved ones with a title, no area, none chosen by an admin,
-      # not asked about yet.
+      # not asked about yet. Announcements cover a whole month and never get one.
       def candidates
         Entry.where(status: %w[draft approved], area_id: nil, area_set_by_admin: false, area_detected_at: nil).where.not(title: [ nil, "" ])
+          .where.not(kind: "announcement")
       end
 
       # Ignores ids outside the batch and areas that don't exist. The update re-checks the conditions, so an

data/app/models/shiplog/change_candidates.rb

@@ -17,6 +17,10 @@ module Shiplog
       repository.pull_requests.awaiting_upgrade_check.where(merged_at: since..).reorder(:merged_at).pick(:merged_at)
     end
 
+    # Node ids of the pull requests (of any repository) linked to an issue that is public or has a public ancestor:
+    # the feature entry of that issue covers them. The lookup reads no instance state.
+    def self.public_tree_pull_request_ids(pull_requests) = allocate.send(:pull_request_ids_in_public_tree, pull_requests)
+
     def initialize(repository:, since:, before:)
       @repository = repository
       @window = since...before

data/app/models/shiplog/drafter.rb

@@ -14,12 +14,14 @@ module Shiplog
     REQUEUE_AFTER = 1.hour
     REQUEUE_LIMIT = 100
 
-    # Returns the new entry, or nil when one already exists for the subject and kind.
-    def self.draft(subject, kind, released_on: nil)
+    # Returns the new entry, or nil when one already exists for the subject and kind. `attributes` are set on a new
+    # entry only (an announcement's slug).
+    def self.draft(subject, kind, released_on: nil, **attributes)
       entry = Entry.create_or_find_by!(subject:, kind:) do |new_entry|
         new_entry.title = subject.title
         new_entry.body = subject.body
         new_entry.released_on = released_on
+        new_entry.assign_attributes(attributes)
       end
       return unless entry.previously_new_record?
 

data/app/models/shiplog/entry.rb

@@ -7,20 +7,31 @@ module Shiplog
     belongs_to :subject, polymorphic: true
     belongs_to :area, class_name: "Shiplog::Area", optional: true
     has_many :translations, class_name: "Shiplog::EntryTranslation", dependent: :destroy, inverse_of: :entry
+    # The newsletter's deliveries of an announcement (see NewsletterDelivery); the database cascades the delete.
+    has_many :newsletter_deliveries, class_name: "Shiplog::NewsletterDelivery", foreign_key: :announcement_id, dependent: :delete_all, inverse_of: :announcement
 
-    enum :kind, %w[roadmap feature change].index_by(&:itself), validate: true
+    enum :kind, %w[roadmap feature change announcement].index_by(&:itself), validate: true
     enum :status, %w[draft approved discarded].index_by(&:itself), default: "draft", validate: true
 
     CHANGELOG_KINDS = %w[feature change].freeze
+    # The slug of a month's announcement ("2026-10"). Features and changes never get one of this shape, so an
+    # announcement's page URL is known before it is drafted.
+    ANNOUNCEMENT_SLUG = /\A\d{4}-\d{2}\z/
 
     validates :released_on, presence: true, if: -> { approved? && !roadmap? }
     validate :area_exists
     validate :kind_change_allowed, on: :update
     validate :kind_free_for_subject, on: :update
 
+    # An announcement that leaves "approved" may be announced again once it is approved again.
+    before_save :clear_announced_at, if: -> { announcement? && will_save_change_to_status? && !approved? }
+
     # Approving an entry, or changing the English text of an approved one, translates it into every configured
     # locale (see TranslateEntryJob). After the commit, so the job reads what was saved.
     after_commit :enqueue_translations, on: :update, if: :translation_due?
+    # Approving an announcement calls config.on_announcement_approved once its translations are current (see
+    # AnnounceJob, which TranslateEntryJob enqueues too).
+    after_commit :enqueue_announcement, on: :update, if: -> { announcement? && approved? && saved_change_to_status? }
 
     SEARCH_MAX_LENGTH = 100
     SEARCH_MAX_WORDS = 5
@@ -84,11 +95,20 @@ module Shiplog
     # at 99. One COUNT over the (status, approved_at) index. It filters on approved_at, not on released_on (the
     # list's order): "new since you last looked" is about when an entry appeared, so an entry approved today
     # with an earlier release date still counts as new.
-    def self.unseen_count(since: nil)
-      scope = approved.where(kind: CHANGELOG_KINDS)
+    def self.unseen_count(since: nil) = count_approved_since(CHANGELOG_KINDS, since)
+
+    # The number of approved announcements approved after `since` (all of them while it is nil), capped at 99.
+    def self.unseen_announcements_count(since: nil) = count_approved_since("announcement", since)
+
+    def self.count_approved_since(kinds, since)
+      scope = approved.where(kind: kinds)
       scope = scope.where("#{table_name}.approved_at > ?", since) if since
       scope.limit(UNSEEN_COUNT_CAP).count
     end
+    private_class_method :count_approved_since
+
+    # Approved announcements: the ones with a public page (config.announcements = :page) or a host link.
+    scope :published_announcements, -> { approved.where(kind: "announcement").where.not(released_on: nil) }
 
     # Gives every published changelog entry that has no slug one (oldest first, so the oldest keeps the plain
     # slug on duplicate titles). Returns how many it filled.
@@ -134,7 +154,11 @@ module Shiplog
       self.kind = value if CHANGELOG_KINDS.include?(kind) && CHANGELOG_KINDS.include?(value)
     end
 
+    # The digest of what a draft was written from: the GitHub title and body, or for an announcement the month's
+    # entries (Period#content_digest). A draft whose stored digest differs is flagged in the admin.
     def self.digest_for(subject)
+      return subject.content_digest if subject.is_a?(Period)
+
       Digest::SHA256.hexdigest([ subject.title, subject.body ].join("\n"))
     end
 
@@ -200,6 +224,40 @@ module Shiplog
       translated.blank? && body.present? ? body : (translated || body)
     end
 
+    # Whether every configured locale has a current translation (always true without config.locales).
+    def translations_current? = Shiplog.config.locales.all? { |locale| translation(locale) }
+
+    # The title, Markdown body, HTML and plain text of an announcement in a locale (the default one when omitted):
+    # the current translation when there is one, else the English text. For config.on_announcement_approved and the
+    # admin's export.
+    def to_markdown(locale = I18n.default_locale) = display_body(locale).to_s
+    def to_html(locale = I18n.default_locale) = Markdown.to_html(display_body(locale))
+    def to_text(locale = I18n.default_locale) = Markdown.to_text(display_body(locale))
+
+    # The absolute URL of the entry's public page (see PublicLinks), or nil without a slug. For an announcement
+    # with config.announcements = :external, the host's own page is elsewhere (config.announcement_url).
+    def public_url = PublicLinks.entry_url(self)
+
+    # Whether the translations an announcement waits for are there: all current, or none can be made because there
+    # is no rewriter (then hosts get the English text, or an admin's hand-made translations).
+    def translations_ready? = Shiplog.config.rewriter.nil? || translations_current?
+
+    # Runs the block (the host's hook, see AnnounceJob) once for this approval, when this is an approved announcement
+    # not announced yet whose translations are ready (`force: true` skips that last check: the admin's "Notify
+    # now"). The block runs under the row lock and announced_at is stored in the same transaction, so two jobs
+    # never both run it, and a block that raises (or a worker that dies) stores nothing and is run again by the
+    # retry. Returns whether the block ran.
+    def announce!(force: false)
+      with_lock do
+        reload
+        next false unless announcement? && approved? && announced_at.nil? && (force || translations_ready?)
+
+        yield
+        update_columns(announced_at: Time.current)
+        true
+      end
+    end
+
     def source_changed?
       source_digest.present? && source_digest != self.class.digest_for(subject)
     end
@@ -214,16 +272,28 @@ module Shiplog
       Shiplog.config.locales.each { |locale| TranslateEntryJob.perform_later(self, locale) }
     end
 
+    # Features and changes get a slug when approved; an announcement gets its month's slug when drafted.
     def permalinked? = CHANGELOG_KINDS.include?(kind)
 
+    # Written whatever this instance holds: AnnounceJob sets the column with update_columns, so an instance loaded
+    # before it may still hold nil and would otherwise see no change to save.
+    def clear_announced_at
+      self.announced_at = nil
+      attribute_will_change!("announced_at")
+    end
+
+    def enqueue_announcement
+      AnnounceJob.perform_later(self)
+    end
+
     # The title parameterized and cut at 80 characters, made unique with -2, -3, ...; entry-<id> when the title
-    # has nothing left. The uniqueness check can lose a race, which the unique index catches (see
-    # retrying_on_slug_conflict).
+    # has nothing left. A month's shape ("2026-10") is kept for announcements and gets a suffix too. The
+    # uniqueness check can lose a race, which the unique index catches (see retrying_on_slug_conflict).
     def generate_slug
       base = dashed_title.first(SLUG_MAX_LENGTH).gsub(/\A-+|-+\z/, "").presence || "entry-#{id}"
       candidate = base
       suffix = 2
-      while self.class.where(slug: candidate).where.not(id:).exists?
+      while ANNOUNCEMENT_SLUG.match?(candidate) || self.class.where(slug: candidate).where.not(id:).exists?
         tail = "-#{suffix}"
         candidate = "#{base.first(SLUG_MAX_LENGTH - tail.length).delete_suffix("-")}#{tail}"
         suffix += 1