Sorry in case this has been asked before: What part of a Julia package API is supposed to by covered by semantic versioning conventions? Everything exported? Everything documented, whether exported or not (unless labeled “experimental” in the package docs)? Or everything that doesn’t start with an underscore?
1 Like
There are some conventions, eg.
-
exported functions,
-
functions with docstrings,
-
functions mentioned in the API docs.
but no hard-and-fast rule. Ideally, export should not be necessary for something to be part of the API, and documenting something does not imply that it is part of the API. Programmers should feel free to document internals.
IMO it is best to say a few sentences in the package docs about what convention you are following. I did this for DynamicHMC.jl.
Some examples: ForwardDiff.jl exports almost nothing. Import what you like, or qualify with the module name. But it is rather well documented. Optim.jl exports some constructs, but not everything, eg some diagnostic accessors are not exported.
Personally, I would just say that what is publicly documented is part of the public API. Nothing else.
1 Like
There are some conventions […] but no hard-and-fast rule […]
Yes. I was wondering if the core devs had some clear community rules in mind (@StefanKarpinski ?), regarding semantic versioning and package APIs. Once a package accumulates a list of dependencies, it would become easier for that package’s maintainers if all of their deps would subscribe to some common conventions.
In many languages, this would be pretty clear (e.g. Java & similar: Is it public or not?). But in Julia, the language itself doesn’t dictate what the public API is. A non-exported function may well be an important part of an API - on the other hand, as you say, packages with many developers may (should?) document internal functionality as well.
There are obviously some “natural” rules here: an exported, documented function is a fairly clear-cut case - but not all cases are this clear. A package developer probably will have a fairly clear idea on what constitutes the public/stable part of their API. I was wondering if we have (or should have) some community standards on how to communicate this idea to the users of the package.
Maybe some docstring macro/decorator to mark something as internal, and another one to mark something as experimental/beta (intended to become part of the public API, users are encouraged to try it out, but no commitment regarding stability of that part of the API yet)?
Maybe we have something like this already?
1 Like