Breaking Change Analysis
Developmentbreaking-change-analysisBreaking 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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
- 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
- Development Workflow — implement required changes using strict TDD
Step 1: Identify the Change Scope
- Determine which classes and methods are affected.
- Check API visibility (
@api publicvs@api privatein YARD docs). - Check if the change affects
Git::Repository(the current facade layer, modules underlib/git/repository/).
Step 2: Find All Usages
-
Internal usages:
grep -rn "method_name" lib/ spec/ -
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
@deprecatedYARD tag with migration guidance - Mark commits with
!for breaking changes and includeBREAKING CHANGE:footer - DO NOT update CHANGELOG.md — it is auto-generated from commit messages