Writing Migration Guides in Release Notes

Migration Guides in Release Notes

When a release includes breaking changes, a migration guide within the release notes helps users upgrade smoothly. The guide should be specific, actionable, and testable.

Structure

## Migration Guide: v1.x to v2.0

### Prerequisites
- Node.js 18 or later
- npm 9 or later
- Back up your configuration files

### Step 1: Update Dependencies

```bash
npm install projectx@2.0.0

Step 2: Update Configuration Format

The config file format changed from JSON to YAML.

Before (v1.x):

{ "port": 3000, "debug": true }

After (v2.0):

port: 3000
debug: true

Run the automatic converter:

npx projectx migrate-config

Step 3: Update API Calls

v1.x Method	v2.0 Method
init(port, opts)	createServer({ port, ...opts })
db.find(query)	db.query(query).exec()
app.route(path, fn)	app.get(path, fn)

Step 4: Run Compatibility Check

npx projectx doctor

This command scans your codebase for deprecated API usage.

Step 5: Test

Run your test suite. Common issues:

• Timeout errors → increase default timeout in config
• Type errors → update TypeScript to 5.0+
• Import errors → update import paths (see below)

Rollback

If you need to rollback:

npm install projectx@1.9.0
git checkout -- config.json

### Best Practices

1. **Automated codemods** — provide scripts that do the migration automatically
2. **Compatibility matrix** — show which versions work together
3. **Progressive migration** — allow migrating one module at a time if possible
4. **Rollback instructions** — always include how to go back
5. **Test commands** — give users a way to verify the migration worked