From 85752db3461153fffcdd522ebe7ee904e42898e5 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Sun, 3 May 2020 14:05:35 -0700 Subject: [PATCH 1/4] Document what public API means --- doc/src/base/base.md | 5 +++++ doc/src/manual/faq.md | 22 ++++++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/doc/src/base/base.md b/doc/src/base/base.md index 180c49f1315bf..bae35ccae2ce7 100644 --- a/doc/src/base/base.md +++ b/doc/src/base/base.md @@ -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 explicitly marked as non-stable. +See [API FAQ](@ref man-api) for more information. + ## Getting Around ```@docs diff --git a/doc/src/manual/faq.md b/doc/src/manual/faq.md index b02f2d20dbd17..03b946edf66bd 100644 --- a/doc/src/manual/faq.md +++ b/doc/src/manual/faq.md @@ -18,6 +18,28 @@ 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 declare 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 explicitly marked as non-stable. +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? + +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 it +into a public API before relying on it. + +### 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? From 53b45de537e8cc86b4cd27203ff45e0931acf880 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Wed, 6 May 2020 21:28:21 -0700 Subject: [PATCH 2/4] Tweak title: How does Julia define its public API? --- doc/src/manual/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/manual/faq.md b/doc/src/manual/faq.md index 03b946edf66bd..941640d0c8b4e 100644 --- a/doc/src/manual/faq.md +++ b/doc/src/manual/faq.md @@ -20,7 +20,7 @@ On the other hand, language *interoperability* is extremely useful: we want to e ## [Public API](@id man-api) -### How does Julia declare public 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 From 83ee22b80b9eee5a0be70d295cebc4bc2682d036 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Wed, 6 May 2020 21:36:01 -0700 Subject: [PATCH 3/4] Try clarifying what "unstable" means --- doc/src/base/base.md | 2 +- doc/src/manual/faq.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/src/base/base.md b/doc/src/base/base.md index bae35ccae2ce7..f600557e27b7e 100644 --- a/doc/src/base/base.md +++ b/doc/src/base/base.md @@ -17,7 +17,7 @@ Some general notes: 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 explicitly marked as non-stable. +[Julia documentation](https://docs.julialang.org/) and not marked as unstable. See [API FAQ](@ref man-api) for more information. ## Getting Around diff --git a/doc/src/manual/faq.md b/doc/src/manual/faq.md index 941640d0c8b4e..f61ea96ca7060 100644 --- a/doc/src/manual/faq.md +++ b/doc/src/manual/faq.md @@ -24,9 +24,9 @@ On the other hand, language *interoperability* is extremely useful: we want to e 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 explicitly marked as non-stable. -Functions, types, and constants are not part of the public API if they are not included in -the documentation, _even if they have docstrings_. +[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? From d7ca01eac16c905ec5c6a3ab96eecef4fbd1d152 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Wed, 13 May 2020 07:24:42 -0700 Subject: [PATCH 4/4] Improve FAQ --- doc/src/manual/faq.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/src/manual/faq.md b/doc/src/manual/faq.md index f61ea96ca7060..75de82a3b9c13 100644 --- a/doc/src/manual/faq.md +++ b/doc/src/manual/faq.md @@ -30,9 +30,14 @@ 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? -Please open an [issue](https://github.com/JuliaLang/julia/issues) or +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 before relying on 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?