shiplog 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0f17beb628a8bf038407c3a1b0e5caa404db7f51eba9472dbf507df7da84431
-  data.tar.gz: da38c5e1bc625bcae2ed31ef037db2440bc94a612760c11cc842cb91b02cdf28
+  metadata.gz: 429880b5cc28e18781af480d464269bbd82a117a76b23746ef1c2e9c2309a6e2
+  data.tar.gz: 418bd44307404a7f9404ae7aed1b444b9c738333b09490cd64027b85a455e231
 SHA512:
-  metadata.gz: 588b5d5e87c63b828d0a75ef4aa01591efec6c94a954622d3ad2e36a6cf88deeb46ae72b19b0f865828606f147dfcdb2b6d30f34ce75741acc23543f9a853d15
-  data.tar.gz: d6a7f52d6df8768e5586a47bbded5e5b867dfaac2ec07e85fd0ac86b37b0a8e4a275db62f7893a1ea8b0f607027924cc50bb4925ff2efb41c9b10e4158bd1a95
+  metadata.gz: 7eacb4b715e25cd9899852abef7d4a8e08dc9b18b9ca1e5f9085193e0447158472a82f049d66d66f8da18d12dbed092609248e0b5f5320ac9b07e78174163ac7
+  data.tar.gz: 4760676c3cfc7fde8d11ad80423c5e9626a581624913c5950986ca8b8ff1708568c4af179f4b06e7ddd9150425cb26fbe41ed29b70d171112c0df9021347ea7d

data/CHANGELOG.md

@@ -1,5 +1,58 @@
 # 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
+
+- Approve, discard and restore update the inbox in place, without a reload. Without JavaScript they still redirect back to the same filtered list.
+- Admins can switch a changelog entry between New feature and Improvement.
+
+### Fixed
+
+- Pull requests whose title starts with a topic (`Importers: …`) are no longer mistaken for a non-changelog Conventional Commits type and skipped; only known types such as `chore:` or `ci:` are.
+- Roadmap drafts are written in the future tense ("You'll be able to…") instead of as if the feature had already shipped, and no longer turn implementation details from the issue into promises such as dates, prices, refunds or limits.
+- Host layouts can render records that the host app routes, such as Active Storage avatars passed to `image_tag`, `link_to` or `url_for`, inside Shiplog's public and admin pages instead of raising `Can't resolve image into URL`.
+- Admin actions return to the filtered list they started from: approving, discarding, restoring or saving an entry keeps the status, kind and page of the inbox.
+- The roadmap board's drag and drop keeps working after Turbo Drive navigation in host apps that use it.
+
 ## 0.1.0 (2026-10-26)
 
 Initial release.

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:
@@ -215,7 +266,7 @@ end
 ## How changelog entries are produced
 
 - **Features**: a public top-level issue closed as completed that has at least one merged linked pull request on itself or a sub-issue. The issue form sections (`### Problem`, `### Before`, `### After`), sub-issue titles and linked pull request titles are given to the rewriter. Only issues closed in the last 90 days are drafted, so a first sync doesn't flood the inbox. The release date is the newest merge date.
-- **Small changes**: the weekly scan looks at pull requests merged, and stored commits made, since the last scan (seven days on the first run). Commits are only considered when they are on the default branch and have no pull request, and their conventional-commit type (`feat:`, `fix(scope):`, ...) must be in `commit_types`. Pull requests are skipped when their title carries a type outside `commit_types`; untyped titles are left for the rewriter to judge. Bot authors are recorded as `name[bot]`, so the default `excluded_authors` pattern matches them.
+- **Small changes**: the weekly scan looks at pull requests merged, and stored commits made, since the last scan (seven days on the first run). Commits are only considered when they are on the default branch and have no pull request, and their conventional-commit type (`feat:`, `fix(scope):`, ...) must be in `commit_types`. Pull requests are skipped when their title starts with a Conventional Commits type (`chore:`, `ci:`, `docs:`, ...) outside `commit_types`; a topic prefix such as `Importers:` is not a type; untyped titles are left for the rewriter to judge. Bot authors are recorded as `name[bot]`, so the default `excluded_authors` pattern matches them.
 - **Exclusions**: pull requests with an excluded label or an excluded author, commits from excluded authors, pull requests that belong to a feature's issue tree (the feature entry covers them), and anything that already has an entry.
 
 ## Approval workflow
@@ -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/application_controller.rb

@@ -3,6 +3,8 @@ module Shiplog
     # Parent controller of the admin. The parent class is resolved when this file loads, so
     # `config.admin_parent_controller` must be set in an initializer (config/initializers/shiplog.rb).
     class ApplicationController < Shiplog.config.admin_parent_controller.constantize
+      include InboxFilters
+
       protect_from_forgery with: :exception
 
       helper Shiplog::FrontendHelper
@@ -15,7 +17,7 @@ module Shiplog
       before_action :authorize_admin
 
       rescue_from Shiplog::Entry::InvalidTransition do
-        redirect_to edit_entry_path(params[:entry_id]), alert: t("shiplog.admin.entries.invalid_transition")
+        respond_inline_error(t("shiplog.admin.entries.invalid_transition"), edit_entry_path(params[:entry_id], inbox_filter_params))
       end
 
       private

data/app/controllers/shiplog/admin/entries/approvals_controller.rb

@@ -5,9 +5,9 @@ module Shiplog
         def create
           entry = Entry.find(params[:entry_id])
           entry.approve!(by: current_admin_name)
-          redirect_to root_path, notice: t("shiplog.admin.entries.approved")
+          respond_inline(entry, :approved)
         rescue ActiveRecord::RecordInvalid => error
-          redirect_to edit_entry_path(entry), alert: error.record.errors.full_messages.to_sentence
+          respond_inline_error(error.record.errors.full_messages.to_sentence, edit_entry_path(entry, inbox_filter_params))
         end
       end
     end

data/app/controllers/shiplog/admin/entries/discards_controller.rb

@@ -6,12 +6,12 @@ module Shiplog
 
         def create
           @entry.discard!(reason: params[:reason].to_s.strip.presence)
-          redirect_to root_path, notice: t("shiplog.admin.entries.discarded")
+          respond_inline(@entry, :discarded)
         end
 
         def destroy
           @entry.restore!
-          redirect_to root_path, notice: t("shiplog.admin.entries.restored")
+          respond_inline(@entry, :restored)
         end
 
         private

data/app/controllers/shiplog/admin/entries/rewrites_controller.rb

@@ -5,7 +5,7 @@ module Shiplog
         def create
           entry = Entry.find(params[:entry_id])
           RewriteEntryJob.perform_later(entry.id, force: true)
-          redirect_to edit_entry_path(entry), notice: t("shiplog.admin.entries.rewrite_queued")
+          redirect_to edit_entry_path(entry, inbox_filter_params), notice: t("shiplog.admin.entries.rewrite_queued")
         end
       end
     end

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

@@ -7,8 +7,8 @@ module Shiplog
       before_action :set_entry, only: %i[edit update]
 
       def index
-        @status = Entry.statuses.key(params[:status].to_s) || "draft"
-        @kind = Entry.kinds.key(params[:kind].to_s)
+        @status = inbox_filter_params[:status] || "draft"
+        @kind = inbox_filter_params[:kind]
         @page = page_number
         scope = Entry.where(status: @status)
         scope = scope.where(kind: @kind) if @kind
@@ -24,10 +24,14 @@ module Shiplog
 
       def update
         if @entry.update(entry_params)
-          redirect_to root_path, notice: t("shiplog.admin.entries.saved")
+          redirect_to root_path(inbox_filter_params), notice: t("shiplog.admin.entries.saved")
         else
           render :edit, status: :unprocessable_content
         end
+      rescue ActiveRecord::RecordNotUnique
+        # Two concurrent kind switches can both pass the validation; the unique index has the last word.
+        @entry.errors.add(:changelog_kind, :taken)
+        render :edit, status: :unprocessable_content
       end
 
       private
@@ -44,7 +48,7 @@ module Shiplog
       end
 
       def entry_params
-        params.expect(entry: %i[title body released_on])
+        params.expect(entry: %i[title body released_on changelog_kind])
       end
 
       def page_number

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

@@ -0,0 +1,55 @@
+module Shiplog
+  module Admin
+    # The drafts inbox state (status, kind, page) carried through every action that leaves the list, so
+    # the admin lands back on the same filtered list. Values are rebuilt from a whitelist and never taken
+    # from a URL or the Referer, so they cannot be used for an open redirect.
+    module InboxFilters
+      extend ActiveSupport::Concern
+
+      MAX_PAGE = 100_000
+
+      included do
+        helper_method :inbox_filter_params
+      end
+
+      # Only present, valid values: { status:, kind:, page: } with any unknown or invalid key dropped.
+      def inbox_filter_params
+        @inbox_filter_params ||= { status: inbox_status, kind: inbox_kind, page: inbox_page }.compact
+      end
+
+      private
+        # Inline (script) requests get the re-rendered row; plain requests redirect back to the filtered list.
+        def respond_inline(entry, message_key)
+          message = t("shiplog.admin.entries.#{message_key}")
+          return redirect_to(root_path(inbox_filter_params), notice: message) unless request.format.json?
+
+          render json: { row: render_inbox_row(entry), matches_filter: inbox_match?(entry), message: message }
+        end
+
+        def respond_inline_error(message, fallback)
+          return render(json: { error: message }, status: :unprocessable_content) if request.format.json?
+
+          redirect_to fallback, alert: message
+        end
+
+        def render_inbox_row(entry)
+          render_to_string(partial: "shiplog/admin/entries/entry_row", formats: :html, locals: { entry: })
+        end
+
+        # Mirrors EntriesController#index: drafts unless a status was given, any kind unless one was.
+        def inbox_match?(entry)
+          entry.status == (inbox_filter_params[:status] || "draft") &&
+            (inbox_filter_params[:kind].nil? || entry.kind == inbox_filter_params[:kind])
+        end
+
+        def inbox_status = Entry.statuses.key(params[:status].to_s) && params[:status].to_s
+
+        def inbox_kind = Entry.kinds.key(params[:kind].to_s) && params[:kind].to_s
+
+        def inbox_page
+          page = Integer(params[:page].to_s, 10, exception: false)
+          page.clamp(1, MAX_PAGE) if page&.positive?
+        end
+    end
+  end
+end

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/frontends_controller.rb

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

data/app/controllers/shiplog/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/admin.css

@@ -70,8 +70,15 @@
   .shiplog-admin .shiplog-admin__flash { border: 1px solid var(--sa-border); border-radius: 0.375rem; padding: 0.5rem 0.75rem; }
   .shiplog-admin .shiplog-admin__flash--alert { border-color: #cf222e; }
 
+  .shiplog-admin .shiplog-admin__live { border: 1px solid var(--sa-border); border-radius: 0.375rem; padding: 0.5rem 0.75rem; }
+  .shiplog-admin .shiplog-admin__live[hidden] { display: none; }
+  .shiplog-admin .shiplog-admin__live--alert { border-color: #cf222e; }
+
   .shiplog-admin .shiplog-admin__title { font-size: 1.5rem; margin: 0 0 1rem; }
   .shiplog-admin .shiplog-admin__muted { color: var(--sa-muted); font-size: 0.875rem; }
+  .shiplog-admin .shiplog-entry-row { transition: opacity 0.2s; }
+  .shiplog-admin .shiplog-entry-row--leaving { opacity: 0; }
+  @media (prefers-reduced-motion: reduce) { .shiplog-admin .shiplog-entry-row { transition: none; } }
   .shiplog-admin .shiplog-admin__empty { color: var(--sa-muted); }
 
   .shiplog-admin .shiplog-admin-filters { display: flex; flex-wrap: wrap; gap: 0.5rem 2rem; margin-bottom: 1rem; }

data/app/frontend/shiplog/board.js

@@ -1,6 +1,9 @@
-const board = document.querySelector("[data-board-url]")
+// Idempotent: runs now and again on turbo:load (inert without Turbo), binding each board once.
+const init = () => {
+  const board = document.querySelector("[data-board-url]")
+  if (!board || board.dataset.shiplogBound) return
+  board.dataset.shiplogBound = "true"
 
-if (board) {
   // Host layouts may not render csrf_meta_tags, so the board element carries the token as a fallback.
   const csrfToken = document.querySelector("meta[name=csrf-token]")?.content ?? board.dataset.csrfToken
   let dragged = null
@@ -75,3 +78,6 @@ if (board) {
     save(list, dragged).catch(() => window.location.reload())
   })
 }
+
+init()
+document.addEventListener("turbo:load", init)