micsapp Linear Upgrade Migration
Contents
Overview
Safely upgrade Linear SDK versions and handle breaking changes with compatibility layers and gradual rollout.
Prerequisites
- Existing Linear integration
- Version control (Git) configured
- Test suite for Linear operations
Instructions
Step 1: Check Current and Latest Versions
set -euo pipefail
npm list @linear/sdk # Current version
npm view @linear/sdk version # Latest available
Step 2: Review Breaking Changes
Check GitHub releases and changelog for migration guides between your current and target versions.
Step 3: Create Upgrade Branch
set -euo pipefail
git checkout -b upgrade/linear-sdk-vX.Y.Z
npm install @linear/sdk@latest
npx tsc --noEmit # Check for type errors
Step 4: Apply Migration Patterns
Common changes between versions: renamed fields, changed return types (direct to paginated), new required parameters, and removed methods.
Step 5: Create Compatibility Layer
Wrap breaking changes in a compat client to normalize behavior across versions.
Step 6: Test and Deploy
set -euo pipefail
npm test && npx tsc --noEmit && npm run lint
npm run deploy:staging && npm run test:integration
Step 7: Gradual Rollout
Use feature flags to toggle between old and new SDK behavior in production.
See detailed implementation for all migration patterns, compatibility layer code, and version-specific changes.
Version Compatibility Matrix
| SDK Version | Node.js | TypeScript | Key Changes |
|---|---|---|---|
| 1.x | 14+ | 4.5+ | Initial release |
| 2.x | 16+ | 4.7+ | ESM support |
| 3.x | 18+ | 5.0+ | Strict types |
Output
- SDK upgraded to target version
- Breaking changes resolved
- Compatibility layer in place
- Tests passing on new version
Error Handling
| Error | Cause | Solution |
|---|---|---|
Property does not exist |
Renamed field | Check migration guide for new name |
Type not assignable |
Changed type | Update type annotations |
Module not found |
ESM/CJS mismatch | Update import syntax |
Runtime method missing |
Version mismatch | Verify installed SDK version |
Examples
Basic usage: Apply linear upgrade migration to a standard project setup with default configuration options.
Advanced scenario: Customize linear upgrade migration for production environments with multiple constraints and team-specific requirements.
Resources
Next Steps
Set up CI/CD integration with linear-ci-integration.