Why We Built a Changelog That Doesn’t Trigger Update Dread — The 3 Rules That Calmed Our Users

TL;DR: “Another update? What’s going to break?” is the default emotion. We fixed this with 3 rules: every breaking change gets a migration guide, every entry links to human-readable diff, zero silent behavior changes. Result: update complaints → 0, upgrade rate → 94% in 7 days. Changelog template →

The Context

Two-dev team, Basso Digital client projects + internal tools. June 2026: Eric Richards’ X post hit 10k+ likes — “Update dread is now the default emotion.” Our own client Slack confirmed it: every dependency update triggered “wait, did this break X?” Realization: Our changelogs were written for us (commit logs), not for users (impact assessment).

What We Tested

Changelog Style	User Reaction	Upgrade Rate (7d)	Support Tickets
Auto-generated (commit messages)	“What changed?” / anxiety	34%	12/update
Feature-list only (“Added X, Fixed Y”)	“Okay but does it break my config?“	52%	7/update
Impact-first (our new format)	“Safe to upgrade — here’s the migration”	94%	0/update

The Pivot Point

June 10, 2026: Shipped Routine v1.3 with a config schema change. Old changelog: “Updated Routine config format.” Result: 3 clients broke production, 2h firefighting. New rule: Every entry must answer “If I upgrade, what exactly do I need to do?” Before merge, changelog entry is required — CI blocks release without it.

What We Use Now

Changelog Entry Template (required for every release):

## [1.3.0] - 2026-06-15

### ⚠️ Breaking Changes
- **Routine config schema v2**: `steps` array now requires `name` field
  - **Migration**: Run `cc routine migrate-config` (auto-patches 95% of cases)
  - **Manual fix**: Add `name: "step-name"` to each step in `.claude/routines/*.yaml`
  - **Rollback**: `git checkout HEAD~1 -- .claude/routines/`

### ✨ New Features
- `fix-tests` Routine: Added `--max-iter` flag (default: 5)
- `scaffold-api`: Now generates OpenAPI 3.1 + Zod v4 schemas

### 🐛 Fixes
- `migrate-db`: Fixed rollback on partial Supabase migration failure
- Token tracker: Correctly handles Claude Code API streaming responses

### 📖 Full Diff
[Human-readable diff: v1.2.0...v1.3.0](https://github.com/basso-digital/tool-crucible/compare/v1.2.0...v1.3.0#diff)

CI Gate (.github/workflows/changelog-check.yml):

- name: Verify changelog entry
  run: |
    if ! grep -q "## \[${VERSION}\]" CHANGELOG.md; then
      echo "❌ Missing changelog entry for $VERSION"
      exit 1
    fi
    if grep -q "BREAKING" CHANGELOG.md && ! grep -q "Migration:" CHANGELOG.md; then
      echo "❌ Breaking change without migration guide"
      exit 1
    fi

When You’d Choose Differently

• Internal tools only: Lighter format fine; team knows context
• High-velocity prototypes (pre-v1): Breaking changes expected; “move fast” > migration docs
• Solo dev, no external consumers: Personal changelog can be commit log

Tool Crucible Rating

Dimension	Rating (1–5)	Notes
Overall	5	Changelog as trust infrastructure, not compliance
Ease of Use	4	Template + CI gate makes it habitual; 2 min overhead
Value	5	Eliminates update dread → faster upgrades → less legacy debt
Support	5	Template is copy-pasteable; CI gate is 15 lines YAML

---

This is part of our Developer Experience series. See template: Changelog Trust Template