How to use the command roave-backward-compatibility-check (with examples)
Roave Backward Compatibility Check is a tool that can be used to verify backward compatibility breaks between two versions of a PHP library. It is designed to help developers ensure that their code changes do not introduce any breaking changes that could affect the dependencies or usage of their PHP library.
Use case 1: Check for breaking changes since the last tag
Code:
roave-backward-compatibility-check
Motivation: This use case is useful when you want to quickly check for any potential backward compatibility breaks in your PHP library since the last tag. By running this command, Roave Backward Compatibility Check will analyze the code changes between the last tagged release and the current code and provide a report on any detected backward compatibility breaks.
Explanation: In this use case, no additional arguments are required. Running the command without any options will trigger Roave Backward Compatibility Check to compare the code differences between versions and identify any potential breaking changes.
Example output:
Checking for backward compatibility breaks since the last tag...
No backward compatibility breaks found.
Use case 2: Check for breaking changes since a specific tag
Code:
roave-backward-compatibility-check --from=git_reference
Motivation: This use case is useful when you want to check for backward compatibility breaks since a specific tag in your PHP library. It allows you to specify a specific tag or git reference as the starting point for the comparison.
Explanation:
To use this use case, you need to provide the --from option followed by the desired git reference. The git reference can be a tag name, commit hash, or any other valid git reference.
Example output:
Checking for backward compatibility breaks since tag v1.0.0...
3 potential backward compatibility breaks found:
1. method MyClass::process() removed
2. constant MY_CONSTANT removed
3. class MyLegacyClass deleted
Use case 3: Check for breaking changes between the last tag and a specific reference
Code:
roave-backward-compatibility-check --to=git_reference
Motivation: This use case is useful when you want to compare the code changes between the last tagged release and a specific reference in your PHP library. It allows you to identify any breaking changes that have occurred within that range.
Explanation:
To use this use case, you need to provide the --to option followed by the desired git reference. The git reference can be a tag name, commit hash, or any other valid git reference.
Example output:
Checking for backward compatibility breaks between the last tag and commit abc123...
1 potential backward compatibility break found:
1. constant MY_CONSTANT changed from 'old_value' to 'new_value'
Use case 4: Check for breaking changes and output to Markdown
Code:
roave-backward-compatibility-check --format=markdown > results.md
Motivation:
This use case is useful when you want to generate a report of the detected backward compatibility breaks in Markdown format. By specifying the --format=markdown option, Roave Backward Compatibility Check will format the output as Markdown and allow you to save it to a file for further reference.
Explanation:
To use this use case, you need to provide the --format option followed by the desired format, which in this case is markdown. Additionally, the output is redirected to a file (results.md) using the > operator.
Example output:
Checking for backward compatibility breaks since the last tag...
No backward compatibility breaks found.
Conclusion
Roave Backward Compatibility Check provides developers with a powerful command-line tool to verify backward compatibility breaks in PHP libraries. It offers flexibility by allowing users to compare code differences between versions, specify specific references, and output the results in different formats. By utilizing the various use cases and understanding the available options, developers can ensure their PHP libraries maintain backward compatibility and avoid any potential breaking changes.
