breaking-change-audit

Breaking-Change Audit

Compare the current public interface against the previous release tag to surface accidental breaking changes before publishing.

Inputs

• Previous tag (defaults to the most recent git tag: git describe --tags --abbrev=0)
• Current version (defaults to HEAD)
• Scope: flags | exit-codes | output-format | all (default)

Steps

1. Build both versions

   # Build HEAD
   cargo build --release
   cp target/release/shipctl /tmp/shipctl-next
   
   # Build the previous tag
   git stash
   git checkout {prev-tag}
   cargo build --release
   cp target/release/shipctl /tmp/shipctl-prev
   git checkout -
   git stash pop
   

2. Diff public flags Capture help output for every command and subcommand:

   /tmp/shipctl-prev --help > /tmp/flags-prev.txt
   /tmp/shipctl-prev release --help >> /tmp/flags-prev.txt
   # ... repeat for all subcommands
   
   /tmp/shipctl-next --help > /tmp/flags-next.txt
   /tmp/shipctl-next release --help >> /tmp/flags-next.txt
   
   diff /tmp/flags-prev.txt /tmp/flags-next.txt
   

   Lines prefixed with - in the diff represent removed flags or changed defaults.

3. Check exit codes Run a battery of known invocations and compare exit codes:

   # Example: unknown flag should exit 2
   /tmp/shipctl-prev --unknown-flag 2>&1; echo "prev exit: $?"
   /tmp/shipctl-next --unknown-flag 2>&1; echo "next exit: $?"
   

   Document any changes; a changed exit code for a common error case is a breaking change.

4. Check output format (JSON / machine-readable outputs)

   /tmp/shipctl-prev release --dry-run --json > /tmp/out-prev.json
   /tmp/shipctl-next release --dry-run --json > /tmp/out-next.json
   diff /tmp/out-prev.json /tmp/out-next.json
   

   Removed JSON keys, renamed fields, or type changes are breaking.

5. Classify findings

   Type	Breaking?	Action
   New flag added	No	Note in changelog under Added
   Flag removed	Yes	Requires BREAKING CHANGE: in commit
   Flag renamed	Yes	Requires BREAKING CHANGE:; add alias for one release cycle
   Default changed	Yes	Requires BREAKING CHANGE:
   Exit code changed	Yes	Requires BREAKING CHANGE:
   New JSON key added	No	Note under Added
   JSON key removed/renamed	Yes	Requires BREAKING CHANGE: