PatchEvergreen Breaking Changes Analyzer

# PatchEvergreen Breaking Changes Analyzer

## Overview

The PatchEvergreen Breaking Changes Analyzer is a specialized skill that helps developers understand, analyze, and plan migrations for library version upgrades. It provides expert guidance on breaking changes, compatibility issues, and migration strategies across multiple programming languages.

This skill works with the PatchEvergreen MCP server to access a comprehensive database of breaking changes for libraries in Python, JavaScript, Java, PHP, Ruby, Go, Rust, and other languages.

## Capabilities

This skill can help you:

- **Analyze Breaking Changes**: Identify and understand breaking changes between library versions
- **Plan Migrations**: Create detailed upgrade plans with step-by-step guidance
- **Assess Compatibility**: Evaluate how breaking changes will impact your codebase
- **Conduct Dependency Audits**: Systematically review all project dependencies for issues
- **Generate Migration Reports**: Create comprehensive reports with actionable recommendations

## Prerequisites

To use this skill, you need:

1. **PatchEvergreen MCP Server**: The skill requires access to the PatchEvergreen MCP server (either stdio or SSE transport)
2. **Library Information**: Know the library name as it appears in package managers (e.g., `requests`, `lodash`, `django`, `phpmailer/phpmailer`)
3. **Language Context**: Identify the programming language of the library

## Library Naming Convention

**Important**: Libraries must be named exactly as they appear in their respective package manager files:

- **Python**: As in `requirements.txt`, `setup.py`, or `pyproject.toml` (e.g., `requests`, `django`, `numpy`)
- **JavaScript/Node.js**: As in `package.json` (e.g., `lodash`, `express`, `react`)
- **PHP**: As in `composer.json` (e.g., `phpmailer/phpmailer`, `symfony/symfony`)
- **Ruby**: As in `Gemfile` (e.g., `rails`, `nokogiri`)
- **Rust**: As in `Cargo.toml` (e.g., `serde`, `tokio`)
- **Java**: As in `pom.xml`, `build.gradle.kts`, or `libs.versions.toml` (e.g., `org.springframework:spring-core`)
- **Go**: As in `go.mod` (e.g., `github.com/gin-gonic/gin`)

## Workflows

### 1. Quick Breaking Changes Check

**When to use**: You need a quick overview of breaking changes for a specific library.

**Process**:
1. Identify the library name and programming language
2. Use the `get_issues_for_library` tool with the library name and language
3. Review the returned breaking changes data
4. Summarize the most critical issues that could affect your codebase

**Example**:
```
Check breaking changes for the Python library "requests"
```

### 2. Comprehensive Breaking Changes Analysis

**When to use**: You need a detailed analysis with migration guidance for a library upgrade.

**Process**:
1. Use the `analyze_breaking_changes` prompt template
2. Provide the library name and language
3. The skill will guide you through:
   - Breaking changes summary
   - Version impact assessment
   - Migration priority ranking
   - Code examples (before/after)
   - Action plan
   - Testing recommendations
   - Timeline estimation

**Example**:
```
Analyze breaking changes for django in Python and provide migration guidance
```

### 3. Dependency Audit

**When to use**: You want to audit all dependencies in a project for breaking changes.

**Process**:
1. Use the `dependency_audit_report` prompt template
2. Specify the project's primary programming language
3. For each dependency you provide:
   - The skill will fetch breaking changes data
   - Classify impact (High/Medium/Low/No Impact)
   - Create an update strategy
   - Provide timeline and resource planning

**Example**:
```
Create a dependency audit report for my Python project. Dependencies: requests, django, numpy
```

### 4. Version Upgrade Planning

**When to use**: You're planning to upgrade a library from one specific version to another.

**Process**:
1. Use the `version_upgrade_planner` prompt template
2. Provide:
   - Library name
   - Programming language
   - Current version
   - Target version
3. The skill will create:
   - Pre-upgrade assessment
   - Incremental upgrade strategy
   - Code impact analysis
   - Testing strategy
   - Implementation plan
   - Change management procedures

**Example**:
```
Plan an upgrade for express (JavaScript) from version 4.17.0 to 5.0.0
```

### 5. Compatibility Impact Summary

**When to use**: You need a focused summary of how breaking changes will affect compatibility.

**Process**:
1. Use the `compatibility_impact_summary` prompt template
2. Provide library name and language
3. The skill will analyze:
   - API breaking changes
   - Configuration changes
   - Behavioral changes
   - Integration impact
   - Migration effort assessment
   - Compatibility recommendations

**Example**:
```
Summarize compatibility impacts for phpmailer/phpmailer in PHP
```

## Best Practices

### Library Name Accuracy
- Always use the exact library name from your package manager file
- For namespaced packages (like PHP's `vendor/package`), include the full namespace
- When in doubt, check your `package.json`, `composer.json`, `requirements.txt`, etc.

### Language Specification
- Use lowercase language names: `python`, `javascript`, `java`, `php`, `ruby`, `go`, `rust`
- For JavaScript, use `javascript` (not `node` or `nodejs`)
- For TypeScript libraries, still use `javascript` as the language

### Incremental Analysis
- Start with a quick check to see if breaking changes exist
- Then use more detailed analysis prompts for libraries with significant changes
- Prioritize high-impact dependencies first

### Version Context
- When planning upgrades, always specify both current and target versions
- Consider intermediate versions if a direct upgrade seems risky
- Review changelogs alongside PatchEvergreen data for complete context

## Integration with MCP Server

This skill is designed to work with the PatchEvergreen MCP server. The server provides:

- **Tool**: `get_issues_for_library(library: str, language: str)` - Fetches breaking changes data
- **Prompts**: Five specialized prompt templates for different analysis scenarios

### MCP Server Connection

**For SSE (Server-Sent Events)**: The server runs on a hosted endpoint and can be accessed via HTTP/SSE transport.

**For stdio**: The server can run locally and communicate via standard input/output.

## Error Handling

If you encounter errors:

1. **Library not found**: Verify the library name matches exactly what's in your package manager file
2. **Language mismatch**: Ensure you're using the correct language identifier (lowercase, standard name)
3. **API errors**: The PatchEvergreen API may be temporarily unavailable; retry after a short delay
4. **No breaking changes**: Some libraries may not have breaking changes recorded in the database

## Examples

### Example 1: Quick Check
```
User: "What breaking changes exist for the Python requests library?"
Skill: Uses get_issues_for_library("requests", "python") and summarizes key breaking changes
```

### Example 2: Migration Planning
```
User: "I need to upgrade Django from 3.2 to 4.2. Help me plan this."
Skill: Uses version_upgrade_planner with library="django", language="python",
       current_version="3.2", target_version="4.2" to create comprehensive plan
```

### Example 3: Project Audit
```
User: "Audit my JavaScript project dependencies: express, lodash, axios"
Skill: Uses dependency_audit_report for each library, creates impact matrix,
       and prioritizes updates
```

## Limitations

- The PatchEvergreen database may not contain all libraries or all breaking changes
- Some breaking changes may be undocumented or not yet recorded
- The skill provides guidance but cannot guarantee complete coverage
- Always test upgrades in a development environment before production deployment

## Support

For issues, questions, or contributions related to this skill or the PatchEvergreen MCP server, please refer to the project repository.

---

*This skill leverages the PatchEvergreen database to help developers make informed decisions about library upgrades and migrations.*