shiplog 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58c17b51ed2b752958414ce03688b5c055681502c6ac9304c2238aab2144e521
-  data.tar.gz: 50ceed3676ed0cb48cb4d8aa3da190456aced0347d62404d3cfa4d095c4cd69e
+  metadata.gz: 429880b5cc28e18781af480d464269bbd82a117a76b23746ef1c2e9c2309a6e2
+  data.tar.gz: 418bd44307404a7f9404ae7aed1b444b9c738333b09490cd64027b85a455e231
 SHA512:
-  metadata.gz: 875076c4feb976490743235f4f56355548518640b15c1fbdb0183afaec7161617a93acb5f199741a6b94c5206d20623aa95b1f9cb63eed5b3823a8190373ab5f
-  data.tar.gz: a16a92cb22802351b8074211400ca12e3ae28f572efffc5fd07fc63fb081a8a27b9c5aa8f530595ebf2f8e53bf5b3a88e62ebcd1f5a24898fb3e2751db602238
+  metadata.gz: 7eacb4b715e25cd9899852abef7d4a8e08dc9b18b9ca1e5f9085193e0447158472a82f049d66d66f8da18d12dbed092609248e0b5f5320ac9b07e78174163ac7
+  data.tar.gz: 4760676c3cfc7fde8d11ad80423c5e9626a581624913c5950986ca8b8ff1708568c4af179f4b06e7ddd9150425cb26fbe41ed29b70d171112c0df9021347ea7d

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.2.0 (2026-10-26)
+
+### Added
+
+- A Roadmap / Changelog switcher in the default page header. Add your own pages with `config.extra_pages` (`[{ label:, path: }]`, each a String or a callable evaluated in the view), and render the same switcher on host pages with `helper Shiplog::SwitcherHelper` and `shiplog_switcher`.
+- Roadmap status by default: a rule and marker per column, a card tag with the issue's repository (`config.repository_labels`), "Includes N parts" on cards, a "Recently shipped" section (`config.roadmap_shipped_count`, default 4, `0` hides it) and an optional footnote with a "Suggest a feature" link (`shiplog.roadmap.footnote`, `config.feedback_path`).
+- New `config.classes` keys: `switcher`, `switcher_link`, `column_marker`, `card_meta`, `card_tag`, `shipped`, `shipped_title`, `shipped_list`, `shipped_item`, `shipped_date`, `shipped_link`, `footnote`, `footnote_link`.
+- Per-repository options in `config.repositories`: `{ name:, changelog: false, gem: }`. `changelog: false` keeps a repository on the roadmap only. `gem:` names the gem in your lockfile so that upgrading it produces a single changelog entry, written from the gem's own merged pull requests, instead of one entry per repository. `config.lockfile_path` changes the lockfile that is read.
+- A Dependabot author, a `chore(deps)` title or the `dependencies` label no longer excludes a pull request that carries gem changes; other excluded labels, such as `internal`, still do.
+- `config.cache_version`, to refresh cached public pages when the output of a configured callable changes.
+- Search on the public changelog: a GET form (`/changelog?q=csv`) that lists approved features and changes whose title or body contain every word of the query, with a result count, a "Clear search" link and pagination that keeps `q`. Turn it off with `config.changelog_search = false`; override `shiplog/changelogs/_search.html.erb` to change it. New `config.classes` keys: `search`, `search_input`, `search_button`, `search_summary`, `search_clear`, `search_empty`. Search pages set `content_for :shiplog_robots, "noindex"` (emitted as a robots meta tag by Shiplog's own layout; add it to your layout, see the README).
+- A Discard button on draft rows of the admin inbox, next to Edit and Approve. It updates the list in place; give a reason from the entry's page.
+
+### Changed
+
+- Roadmap drafts are shorter (about two sentences) and lead with what the customer gets, instead of opening with "We're working on".
+- The roadmap's ETag also covers its recently shipped entries and each card's repository and sub-issues, so those changes reach cached pages.
+- The migration `create_shiplog_pull_request_upgrades` also adds an index on `shiplog_entries (status, released_on)`.
+- Gem upgrade detection: a failure on one pull request no longer blocks the others or keeps the scan window from advancing. Temporary GitHub errors are retried and given up after three attempts; other errors give up at once, with a warning. Pull requests merged before the next scan's start are marked checked without being fetched.
+- Only the last commit's lockfile change is seen for a rebase merge; Dependabot's single-commit pull requests are unaffected.
+
+### Fixed
+
+- The scan window could move back to the oldest pending lockfile pull request after a first sync of a long history, drafting every old pull request and commit in that span. It now never ends before its start.
+- Hosts that mount the engine with another name (`as: :updates`) no longer get a `NameError` from the switcher.
+- The public pages' ETag used a per-process `Hash#hash`, so workers of a multi-process host answered with different ETags for the same page. It is now a stable digest.
+
+### Upgrade notes
+
+- Copy and run the new migration: `bin/rails shiplog:install:migrations`, then `bin/rails db:migrate`. Run it before the job workers start on the new code, because the importer writes the new columns.
+- New I18n keys, all with English defaults, so a locale without translations shows English: `shiplog.switcher.label`, `.roadmap`, `.changelog`; `shiplog.roadmap.parts` (with `count`), `.shipped_heading`, `.shipped_date_format`, `.full_changelog`, `.suggest`; `shiplog.changelog.search.label`, `.submit`, `.summary` (with `count` and `query`), `.clear`, `.empty` (with `query`).
+- The default `shiplog/_page_header` now renders the switcher. Hosts that override `_page_header` keep theirs; render `shiplog_switcher` (or the `shiplog/switcher` partial) in it to get the links.
+- If your app overrides `roadmaps/show`, `_column` or `_card` only to add column status, card tags or recently shipped, delete them and use the new defaults and `config.classes` keys.
+- Style the new elements with the new class keys above if you use `config.classes` with `config.stylesheet = false`.
+- `extra_pages` paths must be absolute (`/…`), `http(s)://` or `mailto:`. A `feedback_path` that is not one of these renders no link.
+- Repository names are validated: anything other than `owner/name` raises `ArgumentError` when `config.repositories` is assigned.
+- For gem upgrades the GitHub token needs read access to **Contents** and **Pull requests** on the gem repositories. Only pull requests synced by 0.2.0 or later are inspected; earlier merges are not backfilled.
+
 ## 0.1.1 (2026-10-26)
 
 ### Added

data/README.md

@@ -82,7 +82,8 @@ All settings live in `config/initializers/shiplog.rb`:
 
 | Key | Default | Description |
 |---|---|---|
-| `repositories` | `[]` | GitHub repositories to sync, as `"owner/name"`. Sub-issues may cross repositories of the same owner. |
+| `repositories` | `[]` | GitHub repositories to sync, as `"owner/name"` or a Hash with options. Sub-issues may cross repositories of the same owner. See [Repositories](#repositories). |
+| `lockfile_path` | `"Gemfile.lock"` | Lockfile read in merged pull requests to detect [gem upgrades](#gem-upgrades). Change it for a monorepo. |
 | `github_token` | `nil` | A String, or a callable evaluated on every GitHub request. |
 | `webhook_secret` | `nil` | Secret of the GitHub webhook. While blank, the webhook endpoint answers 503. |
 | `public_label` | `"public"` | Only issues with this label reach the roadmap. |
@@ -107,6 +108,12 @@ All settings live in `config/initializers/shiplog.rb`:
 | `current_admin` | `->(controller) { controller.try(:current_user)&.try(:email) }` | Stored as the approver of an entry. |
 | `roadmap_path` | `"roadmap"` | Path of the public roadmap. |
 | `changelog_path` | `"changelog"` | Path of the public changelog. |
+| `extra_pages` | `[]` | Pages added to the switcher after Roadmap and Changelog: `[{ label:, path: }]`, each a String or a callable evaluated in the view. See [Product updates navigation](#product-updates-navigation). Anything else raises `ArgumentError`. |
+| `repository_labels` | `{}` | Tag shown on a roadmap card for the repository of its issue: `{ "owner/name" => "iPhone & iPad" }`. Values are Strings or callables evaluated in the view; repositories without one show no tag. |
+| `roadmap_shipped_count` | `4` | How many recently shipped changelog entries (features and changes) the roadmap lists below its columns. `0` hides the section. |
+| `cache_version` | `nil` | A String added to the public pages' ETag. Callables (`extra_pages`, `repository_labels`, `feedback_path`) cannot be fingerprinted, so bump it when the output of a callable you configured changes. |
+| `feedback_path` | `nil` | Target of the roadmap's "Suggest a feature" link, a String or a callable evaluated in the view. No link while `nil`. |
+| `changelog_search` | `true` | Search box on the public changelog and `?q=` filtering. `false` hides the form and ignores `q`. See [Changelog search](#changelog-search). |
 
 Example:
 
@@ -121,6 +128,50 @@ Shiplog.configure do |config|
 end
 ```
 
+## Repositories
+
+Each entry of `config.repositories` is a String (`"owner/name"`) or a Hash:
+
+```ruby
+config.repositories = [
+  "acme/app",
+  "acme/app-ios",
+  { name: "acme/market_data", changelog: false, gem: "market_data" },
+  { name: "acme/produce", changelog: false, gem: "acme-produce" }
+]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `name` | required | `"owner/name"`. |
+| `changelog` | `true` | `false` makes the repository roadmap-only: its issues still feed the roadmap, but its pull requests and commits never become changelog entries. |
+| `gem` | `nil` | The gem's name in your `Gemfile.lock`, for [gem upgrades](#gem-upgrades). |
+
+Unknown options and invalid values raise `ArgumentError` when you assign `repositories`, and so does a name that is not `owner/name` (letters, digits, `.`, `_` and `-`; a segment cannot be only dots). A repository with both `gem:` and `changelog: true` is accepted, but a warning is logged: its changes would be drafted twice, from its own pull requests and from the upgrade. Set `changelog: false`.
+
+`gem:` must be set explicitly because gem names and repository names differ (`acme-produce` lives in `acme/produce`), and a public gem can share a name with one of your repositories without being it: the `holidays` gem from RubyGems is not `acme/holidays`. Matching on names would attach someone else's changes to your changelog, so only gems listed with `gem:` are tracked.
+
+`config.lockfile_path` (default `"Gemfile.lock"`) is the lockfile Shiplog reads in the repositories where `changelog` is true.
+
+## Gem upgrades
+
+A change made in a gem you depend on should appear in the changelog once, when your customers get it: the day your app upgraded the gem. Shiplog does this with the repositories you listed with `gem:`.
+
+For each merged pull request in a repository with `changelog: true` that changes the lockfile:
+
+1. Shiplog reads the lockfile at the merge commit's first parent and at the merge commit itself, and compares the tracked gems with `Bundler::LockfileParser`.
+2. For a gem whose version changed it resolves the tag in the gem's repository (`v<version>` and `<version>`, trying the matching styles first and then the mixed ones). For a git source it uses the locked revision. Shiplog then compares the two refs.
+3. It lists the pull requests merged between the two refs (GitHub's compare API, then the pull requests associated with those commits, the newest 50) and stores them with the upgrade.
+4. The pull request gets one change draft, dated at its merge. The gem's changes (up to 20 titles with excerpts) go into the rewrite prompt, and the rewriter writes one customer-facing entry, or marks it not customer-facing.
+
+A Dependabot bump, a `chore(deps):` title or the `dependencies` label does not exclude a pull request that carries an upgrade with changes; without one it is skipped as usual. Other excluded labels (such as `internal`) still exclude it. If a tag cannot be found, or the gem's repository is not readable by the token, the upgrade is recorded without changes and a warning is logged; the rewriter then works from the pull request alone.
+
+The GitHub token needs read access to the gem repositories as well (**Contents** and **Pull requests**). Detection is capped per sync (50 pull requests), so a large repository's first sync finishes over several syncs.
+
+Only pull requests synced by 0.2.0 or later are inspected: merges imported earlier are not backfilled, and their gem changes are not turned into entries. Pull requests merged before the next scan's start (the last scan, or seven days ago for a repository never scanned) are marked checked without being fetched, since nothing that old would be drafted. A pull request whose inspection fails with a temporary GitHub error is retried on the next syncs and given up after three attempts; any other error gives it up at once, with a warning.
+
+**Rebase merges.** Shiplog reads the lockfile at the merge commit and at its first parent. For a rebase merge, GitHub creates no merge commit: the pull request's "merge commit" is the last rebased commit, so only that commit's lockfile change is seen. Dependabot's pull requests are a single commit, so they are unaffected; a rebased branch that bumps a gem in an earlier commit is missed.
+
 ## GitHub token
 
 Shiplog talks to the GitHub GraphQL API. Provide either:
@@ -226,6 +277,57 @@ Approved changelog entries do not react to later GitHub changes (a reverted pull
 
 Drafts whose rewrite job was lost (no result and no error after an hour) are queued again by the next sync, and the admin marks them "Not rewritten yet" until then.
 
+## Product updates navigation
+
+The default page header shows a switcher under the lede: **Roadmap**, **Changelog**, then `config.extra_pages`. The current page carries `aria-current="page"`: of the pages whose path equals or contains the request path, the one with the longest path is current. Add your own pages, for example a news section:
+
+```ruby
+config.extra_pages = [
+  { label: "News", path: "/learn/news" },
+  # Callables are evaluated in the view, so route helpers and I18n work:
+  { label: -> { t("pages.docs") }, path: -> { main_app.docs_path } }
+]
+```
+
+To show the same switcher on your own pages, add the helper to the controller and call it in the view. It links the stylesheet (unless `config.stylesheet` is `false`) and finds the engine's route proxy in your routes whatever name you gave the mount (`as: :updates`), so it works in main-app views. It raises an error if `Shiplog::Engine` is not mounted:
+
+```ruby
+class NewsController < ApplicationController
+  helper Shiplog::SwitcherHelper
+end
+```
+
+```erb
+<%= shiplog_switcher %>
+```
+
+A `path` String must start with `/` (not `//`, `/\` or `/` followed by whitespace), `http://`, `https://` or `mailto:`, and contain no control characters; anything else, such as `"news"`, raises `ArgumentError` when you assign `extra_pages`. An absolute `http(s)` page is marked current only on its own host (`request.host`). A callable that returns another scheme renders the label as text, without a link, and logs a warning. `feedback_path` follows the same rule at render time: an unsafe value shows no link.
+
+Labels come from `shiplog.switcher.roadmap`, `.changelog` and `.label` (the `nav` label); every Shiplog key has an English default, so a locale without translations shows English. Style it with the `switcher` and `switcher_link` keys of [`config.classes`](#3-configclasses-tailwind-and-other-utility-frameworks); the current link also has `shiplog-switcher__link--current`. Hosts that override `shiplog/_page_header` keep their own header; render `shiplog_switcher` or the `shiplog/switcher` partial in it to get the links.
+
+### Roadmap details
+
+- **Status:** each column has a rule on top and a marker (`shiplog-column__marker--in-progress` / `--coming-soon` / `--later`).
+- **Card meta:** the label of the issue's repository (`config.repository_labels`) and "Includes N parts" when the issue has more than one sub-issue (`shiplog.roadmap.parts`). A card with neither has no meta element.
+- **Recently shipped:** the last `config.roadmap_shipped_count` approved feature and change entries (default 4), each linking to its month on the changelog, plus a "See the full changelog" link. The roadmap's ETag follows changelog approvals.
+- **Footnote:** set the `shiplog.roadmap.footnote` translation (empty by default, nothing renders while it is empty) and `config.feedback_path` for a "Suggest a feature" link (`shiplog.roadmap.suggest`).
+
+## Changelog search
+
+The public changelog has a search form above its months: `GET /changelog?q=csv` lists the approved features and changes whose title or body contain every word of the query (case-insensitive `ILIKE`, so PostgreSQL; `%`, `_` and `\` are matched literally). Only the first 5 words of the first 100 characters count. Results keep the changelog's order and month grouping and are paginated; the pagination links keep `q`. With a query the page shows "N results for “csv”" and a "Clear search" link, or a "no entries match" message. A blank `q` is the same as no `q`. The form is a plain GET form (`role="search"`, a `type="search"` input named `q` with an `aria-label`), so it needs no JavaScript.
+
+- Turn it off with `config.changelog_search = false`: no form, and `q` is ignored.
+- Override `shiplog/changelogs/_search.html.erb` (locals `query:` and `count:`, both `nil` without a query) to change the markup. Style it with the `search*` keys of [`config.classes`](#3-configclasses-tailwind-and-other-utility-frameworks).
+- Texts: `shiplog.changelog.search.label`, `.submit`, `.summary` (`one` / `other`, with `count` and `query`), `.clear` and `.empty` (with `query`); all have English defaults.
+- The ETag includes the normalised query.
+- The model scope is `Shiplog::Entry.search(query)`.
+
+**Keeping search pages out of search engines.** A page with a query sets `content_for :shiplog_robots, "noindex"`. Shiplog's own layout turns that into `<meta name="robots" content="noindex">`. A host layout (`config.public_layout`) controls its own `<head>`, so emit it there:
+
+```erb
+<%= tag.meta name: "robots", content: content_for(:shiplog_robots) if content_for?(:shiplog_robots) %>
+```
+
 ## Styling
 
 The public pages ship plain semantic HTML with stable [BEM](https://getbem.com) classes (`shiplog-card`, `shiplog-entry__title`, ...) and a small, framework-free stylesheet. Pick the level that fits your app; the same views work in all of them.
@@ -300,9 +402,12 @@ Without it, `shiplog` is first seen when `shiplog.css` loads, which can put it a
 | `page_header` | `shiplog-page__header` | Header with title and lede |
 | `page_title` | `shiplog-page__title` | `h1` |
 | `page_lede` | `shiplog-page__lede` | Intro paragraph |
+| `switcher` | `shiplog-switcher` | Switcher `nav` (Roadmap, Changelog, extra pages) |
+| `switcher_link` | `shiplog-switcher__link` (+ `--current`) | One switcher link |
 | `columns` | `shiplog-columns` | Roadmap column grid |
 | `column` | `shiplog-column` (+ `--in-progress` / `--coming-soon` / `--later`) | One roadmap column |
 | `column_header` | `shiplog-column__header` | Column heading block |
+| `column_marker` | `shiplog-column__marker` (+ `--in-progress` / `--coming-soon` / `--later`) | Status dot inside the column `h2`. The column's rule is its `border-top`, set by the column modifier (`shiplog-column--later`); with utility classes, target it with a variant such as `in-[.shiplog-column--later]:bg-gray-300`. |
 | `column_title` | `shiplog-column__title` | Column `h2` |
 | `column_count` | `shiplog-column__count` | Number of items |
 | `column_description` | `shiplog-column__description` | One-line description |
@@ -311,6 +416,16 @@ Without it, `shiplog` is first seen when `shiplog.css` loads, which can put it a
 | `card` | `shiplog-card` | Roadmap card |
 | `card_title` | `shiplog-card__title` | Card `h3` |
 | `card_body` | `shiplog-card__body` | Card text |
+| `card_meta` | `shiplog-card__meta` | Line under the card text (omitted when empty) |
+| `card_tag` | `shiplog-card__tag` | Repository label |
+| `shipped` | `shiplog-shipped` | "Recently shipped" section |
+| `shipped_title` | `shiplog-shipped__title` | Its `h2` |
+| `shipped_list` | `shiplog-shipped__list` | Its list |
+| `shipped_item` | `shiplog-shipped__item` | One entry |
+| `shipped_date` | `shiplog-shipped__date` | Release date of the entry |
+| `shipped_link` | `shiplog-shipped__link` (+ `--all` on the changelog link) | Links to the changelog |
+| `footnote` | `shiplog-footnote` | Footnote paragraph |
+| `footnote_link` | `shiplog-footnote__link` | "Suggest a feature" link |
 | `months` | `shiplog-months` | Changelog months wrapper |
 | `month` | `shiplog-month` | One month section |
 | `month_title` | `shiplog-month__title` | Month `h2` |
@@ -324,16 +439,23 @@ Without it, `shiplog` is first seen when `shiplog.css` loads, which can put it a
 | `pagination` | `shiplog-pagination` | Pagination `nav` |
 | `pagination_link` | `shiplog-pagination__link` (+ `--newer` / `--older`) | Newer/older links |
 | `empty` | `shiplog-empty` | "Nothing here yet" notice |
+| `search` | `shiplog-search` | Changelog search `form` |
+| `search_input` | `shiplog-search__input` | The `type="search"` input |
+| `search_button` | `shiplog-search__button` | Submit button |
+| `search_summary` | `shiplog-search__summary` | "N results for ..." line |
+| `search_clear` | `shiplog-search__clear` | "Clear search" link |
+| `search_empty` | `shiplog-search__empty` | "No entries match" notice |
 
-Values may be strings or arrays. The list is `Shiplog::Classes::KEYS`; assigning `config.classes` raises `ArgumentError` (listing the valid keys) for any other key, in every environment. String keys are accepted and normalised to symbols, and the hash is stored frozen. Texts come from I18n (`shiplog.roadmap.title`, `shiplog.roadmap.lede`, `shiplog.changelog.*`, `shiplog.categories.feature` / `change`, `shiplog.date_format` (default `%-d %B %Y`, used for entry dates), `shiplog.columns.<column>_description`), so override them in your locale files.
+Values may be strings or arrays. The list is `Shiplog::Classes::KEYS`; assigning `config.classes` raises `ArgumentError` (listing the valid keys) for any other key, in every environment. String keys are accepted and normalised to symbols, and the hash is stored frozen. Texts come from I18n (`shiplog.roadmap.title`, `shiplog.roadmap.lede`, `shiplog.roadmap.*` (`parts`, `shipped_heading`, `full_changelog`, `footnote`, `suggest`), `shiplog.switcher.*`, `shiplog.changelog.*`, `shiplog.categories.feature` / `change`, `shiplog.date_format` (default `%-d %B %Y`, used for entry dates), `shiplog.columns.<column>_description`), so override them in your locale files.
 
 ### 4. Override the partials
 
 Copy any view from the engine's `app/views/shiplog/` into your app with the same path and edit it. Each partial documents its locals in a comment on its first lines:
 
 - `shiplog/_page.html.erb`, `shiplog/_page_header.html.erb`, `shiplog/_pagination.html.erb`, `shiplog/_empty.html.erb`
-- `shiplog/roadmaps/_column.html.erb`, `shiplog/roadmaps/_card.html.erb`
-- `shiplog/changelogs/_month.html.erb`, `shiplog/changelogs/_entry.html.erb`
+- `shiplog/_switcher.html.erb`
+- `shiplog/roadmaps/_column.html.erb`, `shiplog/roadmaps/_card.html.erb`, `shiplog/roadmaps/_shipped.html.erb`
+- `shiplog/changelogs/_month.html.erb`, `shiplog/changelogs/_entry.html.erb`, `shiplog/changelogs/_search.html.erb`
 
 `shiplog/_page.html.erb` is what links the stylesheet (so it also works in layouts you don't control); keep that line if you copy it and still want the bundled CSS.
 

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

@@ -4,8 +4,9 @@ module Shiplog
       DELIVERIES_SHOWN = 20
 
       def show
-        repositories = Repository.where(full_name: Shiplog.config.repositories).index_by(&:full_name)
-        @repositories = Shiplog.config.repositories.map { |full_name| [ full_name, repositories[full_name] ] }
+        names = Shiplog.config.repository_names
+        repositories = Repository.where(full_name: names).index_by(&:full_name)
+        @repositories = names.map { |full_name| [ full_name, repositories[full_name] ] }
         @deliveries = WebhookDelivery.order(received_at: :desc, id: :desc).limit(DELIVERIES_SHOWN)
         @webhook_secret_missing = Shiplog.config.webhook_secret.blank?
         @github_token_missing = Shiplog.config.resolved_github_token.blank?

data/app/controllers/shiplog/changelogs_controller.rb

@@ -7,16 +7,26 @@ module Shiplog
       @page = page_number
       scope = Entry.approved.where(kind: %w[feature change]).where.not(released_on: nil)
         .order(released_on: :desc, approved_at: :desc, id: :desc)
+      @query = search_query
+      scope = scope.search(@query) if @query
       records = scope.offset((@page - 1) * PER_PAGE).limit(PER_PAGE + 1).to_a
       return head(:not_found) if @page > 1 && records.empty?
 
       @older = records.size > PER_PAGE
       @months = records.first(PER_PAGE).group_by { |entry| entry.released_on.beginning_of_month }
-      fresh_when etag: [ *shiplog_etag_parts, @page, @older, @months.values.flatten.map { |entry| [ entry.id, entry.updated_at ] } ]
+      @result_count = scope.count if @query
+      fresh_when etag: [ *shiplog_etag_parts, @query, @page, @older, @months.values.flatten.map { |entry| [ entry.id, entry.updated_at ] } ]
     end
 
     private
 
+    # The normalised search query (words joined by one space), or nil when search is off or the query is blank.
+    def search_query
+      return unless Shiplog.config.changelog_search && params[:q].is_a?(String)
+
+      Entry.search_terms(params[:q]).join(" ").presence
+    end
+
     def page_number
       Integer(params[:page].to_s, 10, exception: false).to_i.clamp(1, MAX_PAGE)
     end

data/app/controllers/shiplog/public_controller.rb

@@ -5,6 +5,8 @@ module Shiplog
   class PublicController < Shiplog.config.public_parent_controller.constantize
     helper Shiplog::FrontendHelper
     helper Shiplog::StylingHelper
+    helper Shiplog::SwitcherHelper
+    helper Shiplog::RoadmapHelper
     helper Shiplog::HostRoutesHelper
     layout -> { Shiplog.config.public_layout }
 
@@ -13,7 +15,7 @@ module Shiplog
     # What the rendered markup depends on besides the data: the locale, the gem version and the styling
     # config. Host parent controllers rendering per-user layout content should declare `etag { current_user&.id }`.
     def shiplog_etag_parts
-      [ I18n.locale, Shiplog::VERSION, Shiplog.config.classes.hash, Shiplog.config.stylesheet ]
+      [ I18n.locale, Shiplog::VERSION, Shiplog.config.render_digest ]
     end
   end
 end

data/app/controllers/shiplog/roadmaps_controller.rb

@@ -2,13 +2,36 @@ module Shiplog
   class RoadmapsController < PublicController
     def show
       @columns = Roadmap.new(published_only: true).columns
-      fresh_when etag: [ *shiplog_etag_parts, etag_for(@columns) ]
+      preload_cards(@columns)
+      @shipped = recently_shipped
+      fresh_when etag: [ *shiplog_etag_parts, etag_for(@columns), shipped_etag(@shipped) ]
     end
 
     private
 
+    # The cards read each entry's issue, its repository (label) and its sub-issues (parts).
+    def preload_cards(columns)
+      entries = columns.values.flatten.map(&:entry)
+      ActiveRecord::Associations::Preloader.new(records: entries, associations: { subject: [ :repository, :children ] }).call
+    end
+
+    def recently_shipped
+      count = Shiplog.config.roadmap_shipped_count
+      return Entry.none if count.zero?
+
+      Entry.approved.where(kind: Entry::CHANGELOG_KINDS).where.not(released_on: nil)
+        .order(released_on: :desc, approved_at: :desc, id: :desc).limit(count).load
+    end
+
     def etag_for(columns)
-      columns.transform_values { |items| items.map { |item| [ item.entry.id, item.entry.updated_at ] } }
+      columns.transform_values do |items|
+        items.map do |item|
+          issue = item.entry.subject
+          [ item.entry.id, item.entry.updated_at, issue.updated_at, issue.children.size, issue.repository.full_name ]
+        end
+      end
     end
+
+    def shipped_etag(entries) = entries.map { |entry| [ entry.id, entry.updated_at ] }
   end
 end

data/app/frontend/shiplog/shiplog.css

@@ -67,6 +67,37 @@
   .shiplog-page__title { font-size: 1.875rem; line-height: 1.2; margin: 0; }
   .shiplog-page__lede { color: var(--sl-muted); margin: 0.5rem 0 0; }
 
+  /* Switcher: Roadmap / Changelog / host pages. It can sit outside .shiplog-page (host pages), so it
+     falls back to the host-safe palette when the page variables are not inherited. */
+  .shiplog-switcher {
+    --sw-border: var(--sl-border, var(--shiplog-border, color-mix(in srgb, currentColor 22%, transparent)));
+    --sw-card: var(--sl-card, var(--shiplog-card, color-mix(in srgb, currentColor 5%, transparent)));
+    --sw-muted: var(--sl-muted, var(--shiplog-muted, color-mix(in srgb, currentColor 65%, transparent)));
+    --sw-accent: var(--sl-accent, var(--shiplog-accent, #2f81f7));
+    background: var(--sw-card);
+    border: 1px solid var(--sw-border);
+    border-radius: 999px;
+    display: inline-flex;
+    flex-wrap: wrap;
+    font-size: 0.875rem;
+    font-weight: 500;
+    gap: 0.25rem;
+    margin-top: var(--sl-space, 1rem);
+    padding: 0.25rem;
+  }
+  .shiplog-switcher__link {
+    border-radius: 999px;
+    color: var(--sw-muted);
+    padding: 0.25rem 1rem;
+    text-decoration: none;
+    transition: background-color 0.15s, color 0.15s;
+  }
+  .shiplog-switcher__link:hover { color: inherit; }
+  .shiplog-switcher__link:focus-visible { outline: 2px solid var(--sw-accent); outline-offset: 2px; }
+  .shiplog-switcher__link--current,
+  .shiplog-switcher__link--current:hover { background: var(--sw-accent); color: #fff; }
+  @media (prefers-reduced-motion: reduce) { .shiplog-switcher__link { transition: none; } }
+
   .shiplog-empty,
   .shiplog-column__empty { color: var(--sl-muted); margin: 0; }
 
@@ -77,17 +108,21 @@
     grid-template-columns: repeat(auto-fit, minmax(min(16rem, 100%), 1fr));
   }
 
+  /* A rule on top and a marker carry the column's place in time: in progress is solid, coming soon
+     is the accent, later is neutral. */
   .shiplog-column {
     --sl-dot: var(--sl-muted);
+    --sl-rule: var(--sl-border);
+    border-top: 2px solid var(--sl-rule);
     min-width: 0;
+    padding-top: 1rem;
   }
-  .shiplog-column--in-progress { --sl-dot: #1a7f37; }
-  .shiplog-column--coming-soon { --sl-dot: var(--sl-accent); }
-  .shiplog-column--later { --sl-dot: var(--sl-muted); }
+  .shiplog-column--in-progress { --sl-dot: #1a7f37; --sl-rule: var(--sl-dot); }
+  .shiplog-column--coming-soon { --sl-dot: var(--sl-accent); --sl-rule: var(--sl-dot); }
+  .shiplog-column--later { --sl-dot: var(--sl-muted); --sl-rule: var(--sl-border); }
 
   .shiplog-column__header {
     align-items: baseline;
-    border-bottom: 1px solid var(--sl-border);
     display: flex;
     flex-wrap: wrap;
     gap: 0 0.5rem;
@@ -95,13 +130,14 @@
     padding-bottom: 0.75rem;
   }
   .shiplog-column__title { align-items: center; display: flex; font-size: 1.125rem; gap: 0.5rem; margin: 0; }
-  .shiplog-column__title::before {
+  .shiplog-column__marker {
     background: var(--sl-dot);
     border-radius: 50%;
-    content: "";
+    flex-shrink: 0;
     height: 0.625rem;
     width: 0.625rem;
   }
+  .shiplog-column__marker--in-progress { box-shadow: 0 0 0 4px color-mix(in srgb, var(--sl-dot) 20%, transparent); }
   .shiplog-column__count {
     background: var(--sl-card);
     border: 1px solid var(--sl-border);
@@ -132,6 +168,58 @@
   .shiplog-entry__body p { margin: 0.25rem 0; }
   .shiplog-card__body { color: var(--sl-muted); font-size: 0.9375rem; }
 
+  .shiplog-card__meta {
+    align-items: center;
+    color: var(--sl-muted);
+    display: flex;
+    flex-wrap: wrap;
+    font-size: 0.75rem;
+    font-weight: 500;
+    gap: 0.5rem;
+    margin: 0.75rem 0 0;
+  }
+  .shiplog-card__tag {
+    border: 1px solid var(--sl-border);
+    border-radius: 0.375rem;
+    padding: 0 0.5rem;
+  }
+
+  /* Recently shipped: a title, a link to the full changelog, then a grid of the latest entries */
+  .shiplog-shipped {
+    align-items: baseline;
+    border-top: 1px solid var(--sl-border);
+    display: grid;
+    gap: 0.5rem 1rem;
+    grid-template-columns: 1fr auto;
+    margin-top: calc(var(--sl-space) * 2.5);
+    padding-top: calc(var(--sl-space) * 1.5);
+  }
+  .shiplog-shipped__title { font-size: 1.125rem; margin: 0; }
+  .shiplog-shipped__list {
+    display: grid;
+    gap: var(--sl-space) calc(var(--sl-space) * 1.5);
+    grid-column: 1 / -1;
+    grid-template-columns: repeat(auto-fit, minmax(min(12rem, 100%), 1fr));
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+  .shiplog-shipped__item { display: grid; gap: 0.25rem; align-content: start; }
+  .shiplog-shipped__date { color: var(--sl-muted); font-size: 0.75rem; }
+  .shiplog-shipped__link { color: inherit; font-weight: 600; text-decoration: none; }
+  .shiplog-shipped__link:hover { color: var(--sl-accent); }
+  .shiplog-shipped__link--all { color: var(--sl-accent); font-size: 0.875rem; font-weight: 500; }
+
+  .shiplog-footnote {
+    border-top: 1px solid var(--sl-border);
+    color: var(--sl-muted);
+    font-size: 0.875rem;
+    margin: calc(var(--sl-space) * 2) 0 0;
+    padding-top: var(--sl-space);
+    text-align: center;
+  }
+  .shiplog-footnote__link { color: var(--sl-accent); font-weight: 500; }
+
   /* Changelog: months hang off a vertical line */
   .shiplog-months { display: grid; gap: calc(var(--sl-space) * 2); }
 
@@ -176,6 +264,33 @@
   .shiplog-pagination__link { color: var(--sl-accent); }
   .shiplog-pagination__link--older { margin-left: auto; }
 
+  .shiplog-search { display: flex; flex-wrap: wrap; gap: 0.5rem; margin: var(--sl-space) 0; }
+  .shiplog-search__input {
+    flex: 1 1 14rem;
+    min-width: 0;
+    font: inherit;
+    color: inherit;
+    background: var(--sl-card);
+    border: 1px solid var(--sl-border);
+    border-radius: var(--sl-radius);
+    padding: 0.4rem 0.75rem;
+  }
+  .shiplog-search__input:focus-visible,
+  .shiplog-search__button:focus-visible,
+  .shiplog-search__clear:focus-visible { outline: 2px solid var(--sl-accent); outline-offset: 2px; }
+  .shiplog-search__button {
+    font: inherit;
+    color: #fff;
+    background: var(--sl-accent);
+    border: 1px solid var(--sl-accent);
+    border-radius: var(--sl-radius);
+    padding: 0.4rem 1rem;
+    cursor: pointer;
+  }
+  .shiplog-search__summary { color: var(--sl-muted); margin: 0 0 var(--sl-space); }
+  .shiplog-search__clear { color: var(--sl-accent); margin-left: 0.5rem; }
+  .shiplog-search__empty { color: var(--sl-muted); margin: 0; }
+
   @media (max-width: 40rem) {
     .shiplog-page { padding: var(--sl-space) 0.75rem; }
     .shiplog-page__title { font-size: 1.5rem; }

data/app/helpers/shiplog/callable_helper.rb

@@ -0,0 +1,12 @@
+module Shiplog
+  module CallableHelper
+    # A config value that is a String, or a callable evaluated in the view so it can use route helpers
+    # and I18n (`-> { main_app.news_path }`, `-> { t("...") }`).
+    def shiplog_resolve(value)
+      case value
+      when Proc then instance_exec(&value)
+      else value.respond_to?(:call) ? value.call : value
+      end
+    end
+  end
+end

data/app/helpers/shiplog/frontend_helper.rb

@@ -1,6 +1,7 @@
 module Shiplog
   module FrontendHelper
     def shiplog_stylesheet_tag(name)
+      @_shiplog_stylesheet_emitted = true if name == "shiplog" # shiplog_switcher then skips its own link
       tag.link rel: "stylesheet", href: shiplog_asset_path("#{name}.css"), nonce: content_security_policy_nonce
     end
 

data/app/helpers/shiplog/roadmap_helper.rb

@@ -0,0 +1,15 @@
+module Shiplog
+  module RoadmapHelper
+    include Shiplog::SwitcherHelper
+
+    # The configured label of a repository (config.repository_labels, matched case-insensitively), or nil.
+    def shiplog_repository_label(repository)
+      labels = Shiplog.config.repository_labels
+      label = labels[repository.full_name] || labels.find { |name, _| name.casecmp?(repository.full_name) }&.last
+      shiplog_resolve(label).presence
+    end
+
+    # The "suggest a feature" target (String or callable), or nil.
+    def shiplog_feedback_path = shiplog_safe_url(shiplog_resolve(Shiplog.config.feedback_path))
+  end
+end