sgravrock
commented
3 years ago If there are no comments, I'll close this in a week. Next steps after that:
- Make a PR to DefinitelyTyped to mark all -npm APIs that aren't in the public interface deprecated
- Take into account any feedback that those deprecations provoke
- In 4.0, forbid module subpath imports (e.g.
require('jasmine/lib/somepath')) - Beginning with 4.0, treat anything that's undocumented as a private API
Unlike jasmine-core, the jasmine package (jasmine-npm on github) has historically not defined a distinct public API or taken any particular measures to keep user code from accessing its internals. This is a problem for users because it's harder to tell what the intended usage is, and it's a problem for developers because almost anything is potentially a breaking change. For instance, the addition of ES module support arguably should've required a major version number change because it made some existing functions that were accessible to user code async. That doesn't seem to have actually broken anyone's code, but it could've worked out differently.
I've taken a first pass at defining and documenting a public API. At this point it's mostly an educated guess at what people are actually using. There are probably some things missing. If you use the jasmine NPM package programmatically, please check whether everything you're using is included in the docs. If not, a comment here would be appreciated.
Until the Jasmine 4.0 release (schedule, with apologies to Gary Bernhardt: "things will happen at times"), we'll do our best to avoid breaking anything that's exposed. After that I expect that we'll treat anything not listed in the docs as a private API that can be changed at any time, just like we already do with jasmine-core.