Documenting breaking changes and migration guides

Breaking Changes and Migration Guides

Breaking changes are unavoidable. The quality of your migration guide determines whether developers upgrade or abandon your library. A complete migration guide takes a developer from the old API to the new one without reading your source code.

Migration Guide Structure

## Migrating from v1.x to v2.0

### What changed

`getUserById()` previously threw `NotFoundError` when a user didn't exist.
In v2.0, it returns `null` instead.

### Before (v1.x)

```javascript
try {
  const user = await getUserById(id);
  // use user
} catch (err) {
  if (err instanceof NotFoundError) {
    // handle not found
  }
}
```

### After (v2.0)

```javascript
const user = await getUserById(id);
if (user === null) {
  // handle not found
}
```

### Why this changed

Throwing for "not found" conflated control flow with error handling.
Returning null is idiomatic for lookups that may have no result.

Deprecation Notices

Document deprecations before removal, in the changelog, in the function JSDoc with @deprecated, and with a runtime warning. Minimum one major version between deprecation and removal. Give a concrete timeline: "deprecated in 1.5, removed in 2.0."