# Major framework upgrade, one module per ticket

A major version taken one module at a time, so the upgrade lands in reviewable pieces instead of one unreadable pull request.

Category: Dependency and runtime upgrades
Source: https://letsship.ai/use-cases/major-framework-upgrade-one-module
Published: 2026-08-25

## Goal

Upgrade one module to the new major version of the framework and fix what the new version breaks in it.

## Acceptance criteria

- The module builds and its tests pass on the new major version
- Removed APIs are replaced rather than shimmed
- Anything that could not be migrated is listed in the description with a reason
- No other module is touched

## What lands as proof

A green build for that module on the new major, plus an explicit list of what was left for the next ticket.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Upgrade {module} to {framework} {version}

Description: Upgrade one module to the new major version of the framework and fix what the new version breaks in it.

Acceptance criteria:
- The module builds and its tests pass on the new major version
- Removed APIs are replaced rather than shimmed
- Anything that could not be migrated is listed in the description with a reason
- No other module is touched

Before you create the issue, check which major upgrade this repository is behind on and replace {framework}, {version} and {module} with real values. Pick the module with the fewest dependents to go first.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: upgrade one module to the new major version of the framework and fix what the new version breaks in it. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means module builds, tests green, leftovers listed in the description, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.