# Never Change Public APIs Without a Migration Plan

Breaking changes to public APIs require careful planning and explicit approval.

## What Counts as a Breaking Change

### Function Signatures
- Removing or renaming parameters
- Changing parameter order
- Changing return types
- Adding required parameters

### Data Contracts
- Removing fields from responses
- Changing field types
- Renaming fields
- Changing validation rules

### Behavior Changes
- Different error handling
- Changed default values
- Modified side effects
- Performance characteristics that affect contracts

## Required Migration Plan

Before ANY breaking change, provide:

1. **Deprecation Strategy**
   - Timeline for old API support
   - Warning messages for deprecated usage
   - Migration deadline

2. **Backward Compatibility Approach**
   - Can old code still work?
   - Feature flags or version parameters
   - Parallel API versions

3. **Migration Path**
   - Step-by-step upgrade guide
   - Code examples (before/after)
   - Automated migration tools if applicable

4. **Impact Assessment**
   - Who/what will be affected
   - Number of call sites
   - External vs internal consumers

## Safe Change Patterns

### ✅ Add Optional Parameters
```typescript
// Safe - new optional param
function getUser(id: string, options?: { includeDeleted: boolean })
```

### ✅ Add New Fields to Responses
```typescript
// Safe - additive only
interface UserResponse {
  id: string;
  name: string;
  email: string;  // existing
  avatar?: string; // NEW - optional
}
```

### ✅ Create New API Versions
```
/api/v2/users  // new version
/api/v1/users  // keep old running
```

## What to Do Instead

1. **Ask Permission First**
   "I notice this would be a breaking change. Should I:
   - Create a new version (v2)?
   - Add a deprecation period?
   - Find a backward-compatible approach?"

2. **Propose Alternatives**
   Show non-breaking options before breaking ones

3. **Document the Impact**
   List all affected consumers and required changes

Never silently break contracts. Always communicate breaking changes upfront.