OpenParable
Skip to content
← Back to skills

Breaking Change Analysis

Development
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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/ruby-git/ruby-git/blob/HEAD/.github/skills/breaking-change-analysis/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/breaking-change-analysis, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

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

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:

    grep -rn "method_name" lib/ spec/
    
  2. External usage (if applicable):

    gh search code "Git::Repository#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:

  • Breaking changes are batched for major releases
  • Use deprecation warnings in the current major series before removal in the next major release

Deprecation approach:

# @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