Uselink changelog

Changelog → Uselink

Generate formatted release notes from git history and publish as a shareable uselink page.

When to Use

• "Generate release notes for this version"
• "What shipped this week? Share it."
• "Create a changelog from v1.2 to v1.3"
• "Share what we deployed today"

Prerequisites

which uselink || echo "MISSING"
test -f ~/.uselink/config.json && echo "OK" || echo "NO_CONFIG"

Workflow

1. Determine range

Between tags:

git tag --sort=-version:refname | head -5
git log <old-tag>..<new-tag> --oneline --no-merges

Time-based (last week, last sprint):

git log --since="7 days ago" --oneline --no-merges

Since last deploy (if deploy tags exist):

git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges

If no range specified, default to the last 7 days.

2. Gather data

# All commits in range
git log <range> --format="%H|%an|%s|%ai" --no-merges

# PRs merged in range (if gh is available)
gh pr list --state merged --search "merged:>=<start-date>" --limit 100 \
  --json number,title,author,labels,mergedAt 2>/dev/null

# Group by conventional commit type
git log <range> --oneline --no-merges | grep -c "^[a-f0-9]* feat"
git log <range> --oneline --no-merges | grep -c "^[a-f0-9]* fix"

3. Categorize changes

Group into sections by commit prefix or PR labels:

Category	Commit prefix / label	Icon
New Features	feat, feature	✨
Bug Fixes	fix, bugfix	🐛
Improvements	refactor, perf, improve	⚡
Documentation	docs	📝
Infrastructure	ci, build, chore, deps	🔧
Breaking Changes	BREAKING in body, ! suffix	⚠️

If commits don't follow conventional format, categorize by reading the diff.

4. Generate HTML

Write to /tmp/uselink-changelog-<version>-<timestamp>.html.

<!-- Version header -->
<div class="card">
  <h3>{{VERSION_OR_TITLE}}</h3>
  <p class="muted">{{DATE_RANGE}} · {{COMMIT_COUNT}} commits · {{CONTRIBUTOR_COUNT}} contributors</p>
</div>

<!-- Highlights (top 3-5 most important changes) -->
<h2>Highlights</h2>
<div class="card">
  <ul>
    <li><strong>{{HIGHLIGHT}}</strong> — {{ONE_SENTENCE_DESCRIPTION}}</li>
  </ul>
</div>

<!-- New Features -->
<h2>✨ New Features</h2>
<div class="card">
  <ul><li>{{FEATURE_DESCRIPTION}} <span class="muted">(#{{PR_NUM}})</span></li></ul>
</div>

<!-- Bug Fixes -->
<h2>🐛 Bug Fixes</h2>
<div class="card">
  <ul><li>{{FIX_DESCRIPTION}} <span class="muted">(#{{PR_NUM}})</span></li></ul>
</div>

<!-- Improvements -->
<h2>⚡ Improvements</h2>
<div class="card">
  <ul><li>{{IMPROVEMENT}}</li></ul>
</div>

<!-- Breaking Changes (if any) -->
<h2>⚠️ Breaking Changes</h2>
<div class="card">
  <ul><li><strong>{{BREAKING}}</strong> — {{MIGRATION_NOTES}}</li></ul>
</div>

<!-- Contributors -->
<h2>Contributors</h2>
<p>{{CONTRIBUTOR_LIST}}</p>

5. Publish

uselink publish /tmp/uselink-changelog-<version>-<timestamp>.html \
  --title "Release Notes -- <version or date range>" \
  --format html

Return the URL to the user.

Gotchas

• NEVER set background or color on body, table, th, td, code, or pre. uselink's viewer injects theme-adaptive CSS that handles light/dark mode automatically. Any hardcoded color in published HTML overrides the viewer's theme and forces a white background in dark mode. Only style layout (padding, margins, borders, border-radius, font-size, grid). Use opacity for muted text instead of color: #888.
• Write for the audience, not the git log. "Added real-time notifications for comment replies" is better than "feat(notifications): add WebSocket push for DocumentCommentReply events." Translate commit-speak to user-speak.
• Highlights section is mandatory. Even for small releases, pick the top 3 changes. Stakeholders read this first and may skip the rest.
• Omit noise commits. Skip "fix typo", "lint", "merge branch" commits from the changelog. They're git housekeeping, not release content.
• If no conventional commits, categorize by diff. Read the actual changes to determine if something is a feature, fix, or refactor. Don't just dump uncategorized commits.
• HTML-escape all commit messages and PR titles. They can contain <, >, &.