Problem
It is currently unclear from the README and package documentation which exported functions/types are supported as public APIs, and which are internal implementations that happen to be exported (and may change without notice).
- Users and contributors lack guidance on what parts of each npm package can be safely relied on for long-term usage.
- This can lead to accidental dependence on internal or unstable APIs, resulting in future breakages.
Suggested Improvements
- Explicitly document which exports are considered the publicly supported API (with semver guarantees).
- Mark internal-but-exported symbols as such, with clear guidance that they can change or be removed at any time.
- Consider using JSDoc
@internal or similar tags in source code to further clarify intent.
- Add a summary section in each package's README (especially for
@actions/expressions, etc.) listing the public API surface.
- Reference this documentation from the top-level README.
Motivation
Clear API surface documentation helps external consumers use the packages safely and enhances overall maintainability.
Problem
It is currently unclear from the README and package documentation which exported functions/types are supported as public APIs, and which are internal implementations that happen to be exported (and may change without notice).
Suggested Improvements
@internalor similar tags in source code to further clarify intent.@actions/expressions, etc.) listing the public API surface.Motivation
Clear API surface documentation helps external consumers use the packages safely and enhances overall maintainability.