docs(contributing): tighten public-API checklist for methods, events, and exports#3480
Merged
caio-pizzol merged 1 commit intoMay 25, 2026
Merged
Conversation
… and exports The existing 'Adding a public API' section only covered new public exports. It missed two cases the recent SuperDoc.search regression exposed: - New public method on an existing class: needs explicit Parameters<> and ReturnType<> fixtures. The search regression slipped past every existing gate because the return-type fixture was there but the parameter-type fixture was not. - New event or Config callback: needs a typed-payload fixture AND a runtime test asserting the emitted shape. Types prove consumer usability; runtime tests prove the value the runtime actually emits. Different gates. Also refreshes the stale 'verify-public-facade-emit.cjs ... update the expectedNames array' wording. The expectedNames allowlist was removed when the script started parsing facade source directly (#3476). Adding a named export to the source file is now the only action. PR checklist item generalized to point at all three cases.
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.
Procedural follow-up to PR #3479. The recent
SuperDoc.searchregression (typed asstringinstead ofstring | RegExp) slipped past every existing gate — type checks, the consumer matrix, the deep-type audit, package shape, snapshots, closure, and all 1054 SuperDoc package tests. The bot caught it because no consumer fixture assertedParameters<SuperDoc['search']>[0]. The current CONTRIBUTING section on "Adding a public API" only describes new exports and doesn't say anything about adding methods or events.This PR closes the procedural half of that gap. A coverage gate that mechanically enforces the rule is the next step (planned, separate PR).
What changed
CONTRIBUTING.mdnow spells out three cases instead of one:SuperDoc/DocumentApi/ a UI handle: fixture must assert BOTHParameters<>andReturnType<>. With thesearchregression as the worked example for why both are needed.SuperDocEventMapor newConfig.on*callback: fixture must assert the payload type; for SuperDoc-emitted events, also a runtime test that registers a handler and asserts the emitted shape. Names the type/runtime distinction explicitly so reviewers don't conflate them.superdoc: the existing gate list, with one factual fix —verify-public-facade-emit.cjsno longer maintains anexpectedNamesallowlist (PR refactor(typecheck): derive facade expected names from source files #3476 made it parse facade source directly), so the "update the expectedNames array" sentence is wrong.The PR-checklist item also generalized to point at all three cases instead of just exports.
What this does NOT do
superdoc-public-fixture-coveragescript that walks the SuperDoc class with the TS AST and fails CI when a public method has noParameters<>/ReturnType<>reference in any fixture. Separate PR.SuperDocEventMapevents that SuperDoc emits directly (~9 events, ordered cheap → expensive). Separate PR.Stacked on #3479 (the
.js→.tsmigration). The two are related but independent — this one is comments-only and has no code impact.