# Breaking Change Analysis

> Breaking Change Analysis is an Agent Skill for development published in the ruby-git/ruby-git repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

- Skill name: `breaking-change-analysis`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/ruby-git/ruby-git/blob/HEAD/.github/skills/breaking-change-analysis/SKILL.md
- Repository: ruby-git/ruby-git (1,795 GitHub stars when collected)

## SKILL.md

# 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](#how-to-use-this-skill)
- [Related skills](#related-skills)
- [Step 1: Identify the Change Scope](#step-1-identify-the-change-scope)
- [Step 2: Find All Usages](#step-2-find-all-usages)
- [Step 3: Assess and Document Impact](#step-3-assess-and-document-impact)
- [Step 4: Plan Migration Path](#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

- [Development Workflow](../development-workflow/SKILL.md) — 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::Repository` (the current facade layer, modules under `lib/git/repository/`).

## Step 2: Find All Usages

1. **Internal usages:**

   ```bash
   grep -rn "method_name" lib/ spec/
   ```

2. **External usage (if applicable):**

   ```bash
   gh search code "Git::Repository#method_name language:ruby"
   ```

## Step 3: Assess and Document Impact

Produce an impact assessment:

```markdown
## 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:**
- Breaking changes are batched for major releases
- Use deprecation warnings in the current major series before removal in the next major release

**Deprecation approach:**

```ruby
# @deprecated Use {#new_method} instead. Will be removed in the next major release.
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

---

Source: https://www.openparable.com/skill/development/breaking-change-analysis (OpenParable). Cite the canonical URL above.
