Migration Guide

You are a technical documentation specialist creating migration guides. The user wants to document breaking changes and help developers transition between versions.

What to check first

• Review the CHANGELOG.md or release notes to identify all breaking changes between versions
• Run git log --oneline --grep="BREAKING" to find commits tagged with breaking changes
• Check if there's an existing MIGRATION.md or UPGRADE.md file in the repository root

Steps

1. Create a new MIGRATION.md file in the repository root with a table of contents linking each version migration
2. For each breaking change, use this structure: What changed → Why → Before code example → After code example → Migration path
3. Add a "Quick Start" section at the top with estimated migration time and difficulty level (easy/medium/hard)
4. Document deprecated APIs with a timeline showing when they'll be removed (e.g., "Removed in v3.0, deprecated since v2.5")
5. Create a comparison table showing old vs. new API signatures, parameter names, and return types
6. Include a troubleshooting section with common migration errors and their solutions
7. Add automated migration scripts or codemods in a /migration-scripts directory if applicable
8. Link to specific commit SHAs, PRs, or issue numbers that explain the rationale behind each breaking change

Code

# Migration Guide

## v2.0 → v3.0

**Estimated time:** 30 minutes  
**Difficulty:** Medium

### Quick Links
- [Authentication changes](#authentication-changes)
- [API endpoint updates](#api-endpoint-updates)
- [Configuration structure](#configuration-structure)

---

## Authentication Changes

**What changed:** The authentication system moved from callback-based to Promise-based.

**Why:** Promises provide better error handling and align with modern async patterns.

### Before (v2.x)
```javascript
const auth = require('mylib');

auth.login(username, password, (err, token) => {
  if (err) {
    console.error('Login failed:', err);
  } else {
    console.log('Token:', token);
  }
});

After (v3.0)

const auth = require('mylib');

auth.login(username, password)
  .then(token => console.log('Token:', token))
  .catch(err => console.error('Login failed:', err));

// Or with async/await
async function authenticate() {
  try {
    const token = await auth.login(username, password);
    console.log('Token:', token);
  } catch (err) {
    console.error('Login failed:', err);
  }
}

Migration path:

1. Replace callback parameter with .then() and .catch()
2. Move error handling from first parameter to .catch()
3. Update return value references from callback parameter to .then() parameter

---

API Endpoint Updates

| v2.x

*Note: this example was truncated in the source. See [the GitHub repo](https://github.com/Samarth0211/claude-skills-hub) for the latest full version.*

## Common Pitfalls

- Treating this skill as a one-shot solution — most workflows need iteration and verification
- Skipping the verification steps — you don't know it worked until you measure
- Applying this skill without understanding the underlying problem — read the related docs first


## When NOT to Use This Skill

- When a simpler manual approach would take less than 10 minutes
- On critical production systems without testing in staging first
- When you don't have permission or authorization to make these changes


## How to Verify It Worked

- Run the verification steps documented above
- Compare the output against your expected baseline
- Check logs for any warnings or errors — silent failures are the worst kind


## Production Considerations

- Test in staging before deploying to production
- Have a rollback plan — every change should be reversible
- Monitor the affected systems for at least 24 hours after the change