docs: clarify that breaking/changelog/summary inherit diff behavior

reuvenharrison · claude · reuvenharrison · commit d8ed012fb48e · 2026-04-30T17:52:45.000+03:00
A reader landing on BREAKING-CHANGES.md or CHANGELOG content has no
signal that the flags and concepts in DIFF.md (extension tracking, path
matching, allOf flattening, path-prefix handling, header case,
--allow-external-refs, --fail-on-diff) apply to those commands too.
They do — breaking/changelog/summary all run on the same diff engine.

Adds:
- Top-of-file note in DIFF.md saying most concepts apply to the other
  three commands and exceptions are called out inline
- Top-of-file note in BREAKING-CHANGES.md pointing readers to DIFF.md
  for the shared flag set
- Inline scoping note on --exclude-elements ("currently available on
  diff and summary") so the section remains accurate without baking in
  a permanent design claim

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/BREAKING-CHANGES.md b/docs/BREAKING-CHANGES.md
@@ -4,6 +4,8 @@ The `oasdiff breaking` command displays the breaking changes between OpenAPI spe
 The `oasdiff changelog` command displays all significant changes between OpenAPI specifications, including breaking and non-breaking changes.  
 These commands are typically used in the CI to report or prevent breaking changes.
 
+> **Note:** `breaking` and `changelog` run on the diff engine described in [DIFF.md](DIFF.md). The flags and concepts there — extension tracking, path matching, `allOf` flattening, the path-prefix family, header case, `--allow-external-refs`, `--fail-on-diff` — apply here too, in addition to the breaking-specific options below.
+
 ### Example: display breaking changes
 ```
 oasdiff breaking https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml
diff --git a/docs/DIFF.md b/docs/DIFF.md
@@ -3,6 +3,8 @@ The `oasdiff diff` command displays the diff between OpenAPI specs.
 Output is fully detailed, typically in yaml or json but also available in text, markdown and html formats.  
 This commmand is typically used to generate a structured diff report which can be consumed by other tools but it can also be viewed by humans.
 
+> **Note:** `summary`, `breaking`, and `changelog` are built on the same diff engine. Most concepts and flags described here apply to those commands too. Exceptions are called out inline.
+
 ### Output Formats
 The default diff output format is `yaml`.  
 Additional formats can be generated using the `--format` flag:
@@ -84,6 +86,8 @@ endpoints:
 ```
 
 ### Excluding Specific Kinds of Changes
+Currently available on `diff` and `summary`.
+
 You can use the `--exclude-elements` flag with to exclude one or more of the following:
 - Use `--exclude-elements examples` to exclude [Examples](https://swagger.io/specification/#example-object)
 - Use `--exclude-elements extensions` to exclude [Extensions](https://swagger.io/specification/#specification-extensions)
