ci: comment the public API diff on PRs (informative)#8848
Merged
Conversation
e46a3f9 to
c1e64e4
Compare
c1e64e4 to
5cc5073
Compare
5cc5073 to
8d767a7
Compare
Public API report✅ No public API changes in this PR. |
8d767a7 to
4423c3e
Compare
4423c3e to
48effef
Compare
48effef to
6998e2e
Compare
6998e2e to
ab97abd
Compare
ab97abd to
1516dd0
Compare
1516dd0 to
9973351
Compare
9973351 to
f71191e
Compare
f71191e to
59c34b0
Compare
abb1e23 to
59c34b0
Compare
A pull_request workflow builds a full-signature view of the public API for the PR head and its base from TypeDoc's --json model, diffs them, and posts/updates a sticky comment. Sourcing from TypeDoc means it follows the docs' public-API rules (excludeNotDocumented, @ignore, @Private, the typedoc plugin), so internal or ignored symbols never appear in the report. Never fails the build. - utils/api-surface.mjs: serialises the TypeDoc JSON model into a stable, sorted, fully-qualified, full-signature surface for diffing. - .github/workflows/api-report.yml: builds the base + PR surfaces, diffs them, and posts/updates the sticky comment (continue-on-error so fork PRs stay green).
59c34b0 to
71d5352
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Posts an informative, non-blocking comment on each PR showing how it changes the public API
surface — sourced from TypeDoc, so it follows the exact rules the docs site uses
(
excludeNotDocumented,@ignore,@private, theutils/typedocplugin). Internal / ignored /undocumented symbols never appear (e.g. the
@ignoredappglobal is excluded).A
pull_requestworkflow builds a full-signature API surface for the PR head and its base,diffs them, and posts/updates a sticky comment.
typedoc --json(same config + plugin asnpm run docs) → respects the docs' public-API rulesutils/api-surface.mjsturns the TypeDoc model into a stable, sorted, fully-qualified, full-signature surface (e.g.Vec3.add(rhs: Vec3): Vec3)continue-on-errorutils/api-surface.mjs+.github/workflows/api-report.ymlWhy not api-extractor: it keys off release tags (
@public/@internal) and includes everyexport in the
.d.ts(marking undocumented ones), so it can't honour@ignore/@private/excludeNotDocumented— which this engine uses (323@ignore, 233@private, 0@internal).TypeDoc already implements those rules, so the report is built from its model.
Example
When a PR changes the public surface, the bot posts/updates one sticky comment. Example from a live
test on this PR (a temporary documented export, since reverted):
Public API report
This PR changes the public API surface (+1 / −0), per the docs' rules (@ignore / @Private / undocumented are excluded).
+const API_REPORT_SMOKE_TEST: 42When nothing changes it instead says: ✅ No public API changes in this PR.
Forks
Comments directly, which needs a write token — granted only for same-repo branches. Fork PRs get a
read-only token, so the comment step is skipped (
continue-on-error, so the run stays green withouta comment). Full fork coverage would need the
workflow_runsplit, which can't run from a branchbefore merging.
Cost
Two
typedoc --jsonruns per PR (head + base) — heavier than a unit job, but it's informational andnever gates merges.