breaking-change-analysis

name: breaking-change-analysis description: "Assesses the impact of API changes before implementation to understand what code would break and plan appropriate migration paths. Use when removing methods, changing interfaces, or planning deprecations."

Breaking Change Analysis Workflow

Assess the impact of API changes before implementation. Use when removing methods, changing method signatures, altering return types/values, changing exception types, or modifying default behavior.

Contents

• How to use this skill
• Related skills
• Step 1: Identify the Change Scope
• Step 2: Find All Usages
• Step 3: Assess and Document Impact
• Step 4: Plan Migration Path

How to use this skill

Attach this file to your Copilot Chat context, then invoke it with the specific API/method change you are considering. Use this workflow before coding to assess impact and plan migration.

Related skills

• Review Backward Compatibility — verify backward compatibility after command migrations
• Development Workflow — implement required changes using strict TDD

Step 1: Identify the Change Scope

1. Determine which classes and methods are affected.
2. Check API visibility (@api public vs @api private in YARD docs).
3. Check if the change affects Git::Lib (facade layer used by most callers).

Step 2: Find All Usages

1. Internal usages:

   grep -rn "method_name" lib/ tests/ spec/
   

2. External usage (if applicable):

   gh search code "Git::Base#method_name language:ruby"
   

Step 3: Assess and Document Impact

Produce an impact assessment:

## Breaking Change Impact Assessment

### Change Description
[What is being changed]

### Affected API
- Class: `Git::SomeClass`
- Method: `#some_method`
- Current signature: `def some_method(arg, opts = {})`
- Proposed signature: `def some_method(arg, force: false)`

### Internal Impact
- Files affected: X
- Tests to update: Y

### External Impact
- Severity: [High/Medium/Low]
- Migration difficulty: [Easy/Medium/Hard]

### Migration Path
[How users should update their code]

Step 4: Plan Migration Path

Project versioning policy:

• Current release line: v4.x (heading to v5.0.0)
• Breaking changes are batched for major releases (v5.0.0)
• Use deprecation warnings in the current release line before removal in the next major

Deprecation approach:

# @deprecated Use {#new_method} instead. Will be removed in v5.0.
def old_method(*args)
  warn "[DEPRECATION] `old_method` is deprecated. Use `new_method` instead."
  new_method(*args)
end

Documentation requirements:

• Add @deprecated YARD tag with migration guidance
• Mark commits with ! for breaking changes and include BREAKING CHANGE: footer
• DO NOT update CHANGELOG.md — it is auto-generated from commit messages