Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document what public API means #35715

Merged
merged 4 commits into from
Apr 20, 2021
Merged

Document what public API means #35715

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
85752db
Document what public API means
tkf May 3, 2020
53b45de
Tweak title: How does Julia define its public API?
tkf May 7, 2020
83ee22b
Try clarifying what "unstable" means
tkf May 7, 2020
d7ca01e
Improve FAQ
tkf May 13, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions doc/src/base/base.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,11 @@ Some general notes:
* By convention, function names ending with an exclamation point (`!`) modify their arguments.
Some functions have both modifying (e.g., `sort!`) and non-modifying (`sort`) versions.

The behaviors of `Base` and standard libraries are stable as defined in
[SemVer](https://semver.org/) only if they are documented; i.e., included in the
[Julia documentation](https://docs.julialang.org/) and not marked as unstable.
See [API FAQ](@ref man-api) for more information.

## Getting Around

```@docs
Expand Down
27 changes: 27 additions & 0 deletions doc/src/manual/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,33 @@ For similar reasons, automated translation to Julia would also typically generat

On the other hand, language *interoperability* is extremely useful: we want to exploit existing high-quality code in other languages from Julia (and vice versa)! The best way to enable this is not a transpiler, but rather via easy inter-language calling facilities. We have worked hard on this, from the built-in `ccall` intrinsic (to call C and Fortran libraries) to [JuliaInterop](https://github.com/JuliaInterop) packages that connect Julia to Python, Matlab, C++, and more.

## [Public API](@id man-api)

### How does Julia define its public API?

The only interfaces that are stable with respect to [SemVer](https://semver.org/) of `julia`
version are the Julia `Base` and standard libraries interfaces described in
[the documentation](https://docs.julialang.org/) and not marked as unstable (e.g.,
experimental and internal). Functions, types, and constants are not part of the public
API if they are not included in the documentation, _even if they have docstrings_.

### There is a useful undocumented function/type/constant. Can I use it?

Updating Julia may break your code if you use non-public API. If the code is
self-contained, it may be a good idea to copy it into your project. If you want to rely on
a complex non-public API, especially when using it from a stable package, it is a good idea
to open an [issue](https://github.com/JuliaLang/julia/issues) or
[pull request](https://github.com/JuliaLang/julia/pulls) to start a discussion for turning it
into a public API. However, we do not discourage the attempt to create packages that expose
stable public interfaces while relying on non-public implementation details of `julia` and
buffering the differences across different `julia` versions.

### The documentation is not accurate enough. Can I rely on the existing behavior?

Please open an [issue](https://github.com/JuliaLang/julia/issues) or
[pull request](https://github.com/JuliaLang/julia/pulls) to start a discussion for turning the
existing behavior into a public API.

## Sessions and the REPL

### How do I delete an object in memory?
Expand Down