home / skills / seika139 / dotfiles / breaking_change_in_php_framework

breaking_change_in_php_framework skill

safe

/claude/profiles/cg-m2-mac/skills/breaking_change_in_php_framework

This skill helps assess PHP framework code reviews for breaking changes and ensures proper handling in changelogs and API visibility.

npx playbooks add skill seika139/dotfiles --skill breaking_change_in_php_framework

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.3 KB

---
name: "checking-breaking-changes-in-php-framework"
description: "外部公開を想定したphpフレームワークのコードレビューをする際に、破壊的変更（breaking change）の有無を確認し、破壊的変更がある場合は適切に処理されているかをチェックするスキルです。"
---

# Rules for Breaking Changes in PHP Framework

以下のルールに従って、コードレビュー時に変更が「破壊的変更」か否かを決定する。

## `@internal` tagがついていないクラス

- 公開API(public method)の引数追加やデフォルト値を設定する以外の変更
- APIが変わらない場合もAPI内部実装の変更によりAPIのレスポンスが変化する場合
- 抽象化等により型範囲が広がるが既存と同様のユースケースが可能な場合は破壊的変更扱いしない

## `@internal` tagがついているクラス

- 内部用の実装のため全ての公開APIの変更を破壊的変更扱いしない

## Code Review Checklist

- Pull Request が破壊的変更を含むかどうかをレビューに含めます
- 破壊的変更が行われている場合はその内容が Pull Request の CHANGELOG.md に適切に記載されていることを確認します

Overview

This skill reviews PHP framework changes to detect breaking changes for public, externally visible APIs and verifies that any breaking changes are documented and handled. It applies rules that treat classes tagged @internal differently from public classes. The goal is to prevent accidental API disruptions for external consumers and ensure proper changelog entries when breaking changes occur.

How this skill works

The skill inspects PHP source and docblocks to identify classes and methods, focusing on public methods and their signatures. It flags changes such as argument removals, type alterations, return-value modifications, and unexpected response changes. Classes marked with @internal are treated as internal implementation and their public API changes are not considered breaking. When a breaking change is detected, the skill checks for a clear entry in CHANGELOG.md or the pull request notes.

When to use it

During pull request reviews for libraries and frameworks intended for external use
Before releasing a new minor or major version to confirm compatibility guarantees
When refactoring public classes or altering method signatures
When changing serialization, output formats, or API response structures
When adding abstraction layers or altering return types

Best practices

Treat any public, non-@internal class API changes as potential breaking changes unless only safe additions (optional args with defaults) are made
Document every confirmed breaking change in the changelog and link it in the pull request
Use @internal on implementation-only classes to reduce churn in external APIs
Prefer additive changes (new methods, optional parameters) over removals or narrowing types
Include unit/integration tests that demonstrate preserved behavior for common external use cases

Example use cases

Adding a required parameter to a public method — flag as breaking and require changelog entry
Refactoring internals of a @internal class — do not treat as breaking for external users
Changing a method's return structure that affects JSON responses — mark as breaking and update docs
Widening type hints where existing use cases still work — treat as non-breaking if compatibility preserved
Removing a public method used by consumers — always a breaking change and must be documented

FAQ

Are default-value additions to public method parameters breaking?

Adding parameters with defaults is generally non-breaking because existing callers still work; adding a required parameter is breaking.

What if internal implementation changes alter API responses unintentionally?

If internal changes cause observable response changes for external consumers, treat them as breaking and document them in the changelog.