Shipping Log

Purpose

Turn raw git/GitHub history into a polished, public-facing changelog that reads like a product update — benefit-first, jargon-free, and framed to signal momentum to users and investors. The engineering log says "what was coded"; the shipping log says "what you can now do."

Part of the docs + release pack

This skill is one of three that share a single version anchor with user-guide-builder and screenshot-capture:

docs/VERSION            ← single source of truth (semver, e.g. 1.4.0)
   ├─ shipping-log       → groups releases "## v1.4.0 — 2026-06-17"  (this skill OWNS the bump)
   ├─ user-guide-builder → stamps the guide "Current as of v1.4.0"
   └─ screenshot-capture → captures the app screens (feature art, guide images)

A reader can then match what changed (this log) to how it now works (the guide). After you cut a release here, offer to run user-guide-builder so the guide's stamp matches.

Versioning anchor

A release is one version number over a batch of shipped work. Manage it with the bundled scripts/version.mjs (dependency-free, cross-platform):

• minor — new user-facing features (most releases) · patch — fixes/polish only ·

major — breaking change or headline launch.

• Group the log by version, newest first: ## v{X.Y.Z} — {date}. Everything since the

previous ## v… heading (or git tag) goes under the new version.

• First-time / backfill: reconstruct a few version buckets from history so the log opens

with momentum (pre-GA products stay in 0.x); set the anchor to the newest bucket and say in your report that early versions were reconstructed.

Workflow

1. Collect history. From the repo root, run the bundled script:

   node <skill-dir>/scripts/collect-history.mjs --days 5

• Use --since-tag instead of --days N to scope from the latest git tag to HEAD.
• Add --github to also pull merged PR titles + releases via the gh CLI (best-effort; skipped if gh is unauthenticated).
• Output is JSON: momentum stats, tags, and commits grouped by day. Read it; do not guess history.

1. Load the voice guide. Read references/voice-and-format.md for the tone rules, the

commit→section mapping, the omit list, the exact markdown format, and a worked example. Follow it exactly — the value of this skill is the consistent voice.

1. Translate, don't transcribe. Group commits by version (default — see

Versioning anchor), or by day/release/tag. For each entry write a one-line headline + 2–4 benefit bullets + section tags (New / Improved / Fixed / Security). Merge many small commits into a few user-meaningful bullets.

1. Compute momentum stats from the JSON for the header strip: updates this week, releases,

last shipped. These are the numbers investors scan first.

1. Pick the output based on the request:

• Markdown changelog (default) — write docs/SHIPPING-LOG.md (or CHANGELOG.md),

newest first, grouped by version (## v1.4.0 — 2026-06-17).

• Standalone "What's New" page — copy assets/whats-new.html for a full-page, premium,

themeable changelog (version-grouped, category filter chips, momentum band, works without JS). Set the :root brand tokens to the project's real colors — never invent a palette.

• Landing-page section — copy assets/shipping-log.html, fill in the entries and the

illustration slots, and adapt to the project's stack (convert to React/TSX if the repo is React; keep the structure and class names).

1. Be honest about ship status. Clearly mark un-merged/un-deployed work as "rolling out" or

"staged" — never imply staged work is live. Check git status / whether commits are pushed if in doubt.

Non-negotiable rules

• Benefit-first. Lead with what the user/customer can now do, not the implementation.
• No internal jargon. Translate engineering terms to product impact. "Enabled RLS" → "your

data is now isolated to your account"; "removed @ts-nocheck / refactor / bumped deps" → omit or fold into one "Behind the scenes" line.

• Never invent. Every entry must trace to a real commit/PR in the collected JSON. If a commit's

user impact is unclear, inspect the diff, ask, or omit it — do not fabricate a feature.

• Sentence case, punchy, scannable. One screenful per release. Two weights, no ALL CAPS.

Portfolio mode (one board across many repos)

To build a "we ship across everything" board (a portfolio ship index), aggregate multiple repos:

1. Copy assets/portfolio.config.example.json and edit the projects list (name, local repo

path, tagline, accent). One entry per app.

1. Run node <skill-dir>/scripts/collect-portfolio.mjs --config <your-config>.json --days 35.

Output JSON has: totals (ships_this_week, ships_30d, active_this_week, busiest_day), a merged daily heatmap map, per-projects stats, and the latest cross-project recent commits.

1. Render the Ship Index: portfolio stat strip + a 5-week activity heatmap (color cells by daily

count) + per-project rows (bar width ∝ 30-day commits) + a cross-project recent-ships feed. Rewrite recent[].subject (raw commit messages) into benefit-first copy per the voice spec.

1. Data source choice when wiring to a real site:

• Static/generated (repos are local or in CI): run the aggregator on a schedule, write the

JSON into the home-page repo (or an endpoint), and have the page read it. No live git needed.

• GitHub-API live: if every repo is on GitHub, a serverless function can hit the commits API

per repo and aggregate on request — always fresh, no local step. Needs a token + repo list.

• Keep cadence claims truthful; show dormant projects honestly (or feature only active ones).

Reusable contents

• scripts/version.mjs — the shared semver anchor manager (get/init/set/bump/date on docs/VERSION).
• scripts/collect-history.mjs — single-repo history collector (run, don't reinvent).
• scripts/collect-portfolio.mjs — multi-repo aggregator for the portfolio ship index.
• assets/portfolio.config.example.json — example portfolio config.
• references/voice-and-format.md — the voice + format spec and worked example.
• assets/whats-new.html — a standalone, premium, themeable "What's New" page (version-grouped,

category filter chips, momentum band; works without JS). Pairs with docs/SHIPPING-LOG.md.

• assets/shipping-log.html — a dark, on-brand landing "shipping log" section (single product)

with metric strip, timeline cards, illustration slots, and notes for adapting to React.