Version migration notes and upgrade guidance #24

New issue

Open

opened 2026-01-05 21:17:27 +00:00 by mprihoda · 0 comments

mprihoda commented

2026-01-05 21:17:27 +00:00

(Migrated from github.com)

Problem

Agent encounters deprecated patterns or needs to upgrade library versions:

"This code uses `IO.shift` but it's gone in cats-effect 3"
"How do I migrate from Circe 0.13 to 0.14?"
"What changed between ZIO 1 and ZIO 2?"

Proposed Solution

New Tool: `get_migration_notes`

{
  "name": "get_migration_notes",
  "description": "Get migration guidance between library versions",
  "input": {
    "coordinates": "Library (groupId::artifactId)",
    "fromVersion": "Current version",
    "toVersion": "Target version"
  }
}

Example:

get_migration_notes("org.typelevel::cats-effect", "2.5.5", "3.5.4")

Returns:

## Migration: cats-effect 2.x → 3.x

### Breaking Changes

| 2.x | 3.x | Notes |
|-----|-----|-------|
| \`IO.shift\` | Removed | Automatic on async boundaries |
| \`ContextShift[IO]\` | Removed | Built into \`IO\` |
| \`Blocker\` | Removed | Not needed with virtual threads |
| \`Timer[IO]\` | \`Temporal[IO]\` | Renamed, different API |

### Code Migrations

**Before (2.x):**
\`\`\`scala
implicit val cs: ContextShift[IO] = IO.contextShift(ec)
implicit val timer: Timer[IO] = IO.timer(ec)

for {
  _ <- IO.shift
  result <- computation
} yield result
\`\`\`

**After (3.x):**
\`\`\`scala
// No implicits needed, just:
for {
  result <- computation
} yield result
\`\`\`

### Dependency Changes
- Add: \`"org.typelevel" %% "cats-effect" % "3.5.4"\`
- Remove: \`"org.typelevel" %% "cats-effect-laws" % "2.x"\`
- Replace with: \`"org.typelevel" %% "cats-effect-testkit" % "3.5.4"\`

### Recommended Reading
- [Migration Guide](https://typelevel.org/cats-effect/docs/migration-guide)

Implementation Sources

CHANGELOG files from Maven Central/GitHub
Migration guides from library docs sites
Curated knowledge base for major libraries
Deprecation annotations from source/TASTy

Scope

Start with major Scala libraries:

cats-effect 2→3
ZIO 1→2
Circe major versions
http4s versions
Play Framework versions

Value for Agent

Knows how to update deprecated code
Understands what changed between versions
Can modernize legacy codebases

Acceptance Criteria

Support at least 3 major libraries
Identify breaking changes
Provide before/after code examples
Link to official migration guides

## Problem Agent encounters deprecated patterns or needs to upgrade library versions: - "This code uses \`IO.shift\` but it's gone in cats-effect 3" - "How do I migrate from Circe 0.13 to 0.14?" - "What changed between ZIO 1 and ZIO 2?" ## Proposed Solution ### New Tool: \`get_migration_notes\` ```json { "name": "get_migration_notes", "description": "Get migration guidance between library versions", "input": { "coordinates": "Library (groupId::artifactId)", "fromVersion": "Current version", "toVersion": "Target version" } } ``` **Example:** ``` get_migration_notes("org.typelevel::cats-effect", "2.5.5", "3.5.4") ``` **Returns:** ```markdown ## Migration: cats-effect 2.x → 3.x ### Breaking Changes | 2.x | 3.x | Notes | |-----|-----|-------| | \`IO.shift\` | Removed | Automatic on async boundaries | | \`ContextShift[IO]\` | Removed | Built into \`IO\` | | \`Blocker\` | Removed | Not needed with virtual threads | | \`Timer[IO]\` | \`Temporal[IO]\` | Renamed, different API | ### Code Migrations **Before (2.x):** \`\`\`scala implicit val cs: ContextShift[IO] = IO.contextShift(ec) implicit val timer: Timer[IO] = IO.timer(ec) for { _ <- IO.shift result <- computation } yield result \`\`\` **After (3.x):** \`\`\`scala // No implicits needed, just: for { result <- computation } yield result \`\`\` ### Dependency Changes - Add: \`"org.typelevel" %% "cats-effect" % "3.5.4"\` - Remove: \`"org.typelevel" %% "cats-effect-laws" % "2.x"\` - Replace with: \`"org.typelevel" %% "cats-effect-testkit" % "3.5.4"\` ### Recommended Reading - [Migration Guide](https://typelevel.org/cats-effect/docs/migration-guide) ``` ## Implementation Sources 1. **CHANGELOG files** from Maven Central/GitHub 2. **Migration guides** from library docs sites 3. **Curated knowledge base** for major libraries 4. **Deprecation annotations** from source/TASTy ## Scope Start with major Scala libraries: - cats-effect 2→3 - ZIO 1→2 - Circe major versions - http4s versions - Play Framework versions ## Value for Agent - Knows how to update deprecated code - Understands what changed between versions - Can modernize legacy codebases ## Acceptance Criteria - [ ] Support at least 3 major libraries - [ ] Identify breaking changes - [ ] Provide before/after code examples - [ ] Link to official migration guides