From 2b7766a7666934e7fe0ffa00f3b895b7c14f91f0 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Sat, 4 Jul 2026 16:12:15 +0300 Subject: [PATCH] docs: state what changelog, breaking, and diff each cover The changelog action was described as outputting "all changes", which is not what it does: documentation-only edits such as descriptions and examples are not reported by any check. Name the boundary consistently across the three actions: changelog shows the changes that can affect API consumers; breaking shows the changes that break existing API clients; diff shows the full diff of the API definition, including documentation-only edits. Co-Authored-By: Claude Fable 5 --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d443746..513a69b 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ The following actions run the oasdiff CLI directly in your GitHub runner — no ### Check for breaking changes -Detects breaking changes and writes inline `::error::` annotations on the pull request's Files changed tab. Fails the workflow when changes at or above the `fail-on` severity are found. When changes are found it also uploads the comparison and links to a full side-by-side review (the `review` input, on by default); the two specs are encrypted in CI before upload, so the server cannot read them. The link is posted as a pull-request comment when you pass `github-token` (and grant `pull-requests: write`); otherwise, and on fork PRs where the token is read-only, it falls back to the job summary. +Detects changes that break existing API clients and writes inline `::error::` annotations on the pull request's Files changed tab. Fails the workflow when changes at or above the `fail-on` severity are found. When changes are found it also uploads the comparison and links to a full side-by-side review (the `review` input, on by default); the two specs are encrypted in CI before upload, so the server cannot read them. The link is posted as a pull-request comment when you pass `github-token` (and grant `pull-requests: write`); otherwise, and on fork PRs where the token is read-only, it falls back to the job summary. ```yaml name: oasdiff @@ -116,7 +116,7 @@ jobs: ### Generate a changelog -Outputs all changes (breaking and non-breaking) between two specs. When changes are found it also uploads the comparison and links to a full side-by-side review (the `review` input, on by default); the two specs are encrypted in CI before upload, so the server cannot read them. The link is posted as a pull-request comment when you pass `github-token` (and grant `pull-requests: write`); otherwise, and on fork PRs where the token is read-only, it falls back to the job summary. +Outputs the changes that can affect API consumers (breaking and non-breaking) between two specs. Documentation-only edits, such as descriptions and examples, are not included; use the diff action to see every difference in the API definition. When changes are found it also uploads the comparison and links to a full side-by-side review (the `review` input, on by default); the two specs are encrypted in CI before upload, so the server cannot read them. The link is posted as a pull-request comment when you pass `github-token` (and grant `pull-requests: write`); otherwise, and on fork PRs where the token is read-only, it falls back to the job summary. ```yaml name: oasdiff @@ -161,7 +161,7 @@ jobs: ### Generate a diff report -Outputs the raw structural diff between two specs. +Outputs the full diff of the API definition between two specs, including documentation-only edits. ```yaml name: oasdiff