This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 12cb1bee26 Publish built docs triggered by
8b6daaf6f1f9be3043f9f90e56e3b15e694a4974
12cb1bee26 is described below
commit 12cb1bee263bc1153031ad2c78945b6c37200c16
Author: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
AuthorDate: Fri Dec 13 18:19:02 2024 +0000
Publish built docs triggered by 8b6daaf6f1f9be3043f9f90e56e3b15e694a4974
---
_sources/library-user-guide/api-health.md.txt | 46 ++++++++++++++++++++--
library-user-guide/api-health.html | 55 ++++++++++++++++++++++++---
searchindex.js | 2 +-
3 files changed, 92 insertions(+), 11 deletions(-)
diff --git a/_sources/library-user-guide/api-health.md.txt
b/_sources/library-user-guide/api-health.md.txt
index 943a370e81..46a894d4d5 100644
--- a/_sources/library-user-guide/api-health.md.txt
+++ b/_sources/library-user-guide/api-health.md.txt
@@ -19,13 +19,51 @@
# API health policy
-To maintain API health, developers must track and properly deprecate outdated
methods.
+DataFusion is used extensively as a library and has a large public API, thus it
+is important that the API is well maintained. In general, we try to minimize
+breaking API changes, but they are sometimes necessary.
+
+When possible, rather than making breaking API changes, we prefer to deprecate
+APIs to give users time to adjust to the changes.
+
+## Breaking Changes
+
+In general, a function is part of the public API if it appears on the [docs.rs
page]
+
+Breaking public API changes are those that _require_ users to change their code
+for it to compile, and are listed as "Major Changes" in the [SemVer
+Compatibility Section of the cargo book]. Common examples of breaking changes:
+
+- Adding new required parameters to a function (`foo(a: i32, b: i32)` ->
`foo(a: i32, b: i32, c: i32)`)
+- Removing a `pub` function
+- Changing the return type of a function
+
+When making breaking public API changes, please add the `api-change` label to
+the PR so we can highlight the changes in the release notes.
+
+[docs.rs page]: https://docs.rs/datafusion/latest/datafusion/index.html
+[semver compatibility section of the cargo book]:
https://doc.rust-lang.org/cargo/reference/semver.html#change-categories
+
+## Deprecation Guidelines
+
When deprecating a method:
-- clearly mark the API as deprecated and specify the exact DataFusion version
in which it was deprecated.
-- concisely describe the preferred API, if relevant
+- Mark the API as deprecated using `#[deprecated]` and specify the exact
DataFusion version in which it was deprecated
+- Concisely describe the preferred API to help the user transition
+
+The deprecated version is the next version which contains the deprecation. For
+example, if the current version listed in [`Cargo.toml`] is `43.0.0` then the
next
+version will be `44.0.0`.
+
+[`cargo.toml`]: https://github.com/apache/datafusion/blob/main/Cargo.toml
+
+To mark the API as deprecated, use the `#[deprecated]` attribute like this:
+
+```rust
+ #[deprecated(since = "...", note = "...")]
+```
-API deprecation example:
+For example:
```rust
#[deprecated(since = "41.0.0", note = "Use SessionStateBuilder")]
diff --git a/library-user-guide/api-health.html
b/library-user-guide/api-health.html
index 07ba5c8008..24393cb304 100644
--- a/library-user-guide/api-health.html
+++ b/library-user-guide/api-health.html
@@ -497,9 +497,24 @@
<div class="toc-item">
+<div class="tocsection onthispage pt-5 pb-3">
+ <i class="fas fa-list"></i> On this page
+</div>
<nav id="bd-toc-nav">
-
+ <ul class="visible nav section-nav flex-column">
+ <li class="toc-h2 nav-item toc-entry">
+ <a class="reference internal nav-link" href="#breaking-changes">
+ Breaking Changes
+ </a>
+ </li>
+ <li class="toc-h2 nav-item toc-entry">
+ <a class="reference internal nav-link" href="#deprecation-guidelines">
+ Deprecation Guidelines
+ </a>
+ </li>
+</ul>
+
</nav>
</div>
@@ -546,19 +561,47 @@
-->
<section id="api-health-policy">
<h1>API health policy<a class="headerlink" href="#api-health-policy"
title="Link to this heading">¶</a></h1>
-<p>To maintain API health, developers must track and properly deprecate
outdated methods.
-When deprecating a method:</p>
+<p>DataFusion is used extensively as a library and has a large public API,
thus it
+is important that the API is well maintained. In general, we try to minimize
+breaking API changes, but they are sometimes necessary.</p>
+<p>When possible, rather than making breaking API changes, we prefer to
deprecate
+APIs to give users time to adjust to the changes.</p>
+<section id="breaking-changes">
+<h2>Breaking Changes<a class="headerlink" href="#breaking-changes" title="Link
to this heading">¶</a></h2>
+<p>In general, a function is part of the public API if it appears on the <a
class="reference external"
href="https://docs.rs/datafusion/latest/datafusion/index.html";>docs.rs
page</a></p>
+<p>Breaking public API changes are those that <em>require</em> users to change
their code
+for it to compile, and are listed as “Major Changes” in the <a
class="reference external"
href="https://doc.rust-lang.org/cargo/reference/semver.html#change-categories";>SemVer
+Compatibility Section of the cargo book</a>. Common examples of breaking
changes:</p>
+<ul class="simple">
+<li><p>Adding new required parameters to a function (<code class="docutils
literal notranslate"><span class="pre">foo(a:</span> <span
class="pre">i32,</span> <span class="pre">b:</span> <span
class="pre">i32)</span></code> -> <code class="docutils literal
notranslate"><span class="pre">foo(a:</span> <span class="pre">i32,</span>
<span class="pre">b:</span> <span class="pre">i32,</span> <span
class="pre">c:</span> <span class="pre">i32)</span></code>)</p></li>
+<li><p>Removing a <code class="docutils literal notranslate"><span
class="pre">pub</span></code> function</p></li>
+<li><p>Changing the return type of a function</p></li>
+</ul>
+<p>When making breaking public API changes, please add the <code
class="docutils literal notranslate"><span class="pre">api-change</span></code>
label to
+the PR so we can highlight the changes in the release notes.</p>
+</section>
+<section id="deprecation-guidelines">
+<h2>Deprecation Guidelines<a class="headerlink" href="#deprecation-guidelines"
title="Link to this heading">¶</a></h2>
+<p>When deprecating a method:</p>
<ul class="simple">
-<li><p>clearly mark the API as deprecated and specify the exact DataFusion
version in which it was deprecated.</p></li>
-<li><p>concisely describe the preferred API, if relevant</p></li>
+<li><p>Mark the API as deprecated using <code class="docutils literal
notranslate"><span class="pre">#[deprecated]</span></code> and specify the
exact DataFusion version in which it was deprecated</p></li>
+<li><p>Concisely describe the preferred API to help the user
transition</p></li>
</ul>
-<p>API deprecation example:</p>
+<p>The deprecated version is the next version which contains the deprecation.
For
+example, if the current version listed in <a class="reference external"
href="https://github.com/apache/datafusion/blob/main/Cargo.toml";><code
class="docutils literal notranslate"><span
class="pre">Cargo.toml</span></code></a> is <code class="docutils literal
notranslate"><span class="pre">43.0.0</span></code> then the next
+version will be <code class="docutils literal notranslate"><span
class="pre">44.0.0</span></code>.</p>
+<p>To mark the API as deprecated, use the <code class="docutils literal
notranslate"><span class="pre">#[deprecated]</span></code> attribute like
this:</p>
+<div class="highlight-rust notranslate"><div
class="highlight"><pre><span></span><span class="w"> </span><span
class="cp">#[deprecated(since = </span><span
class="s">"..."</span><span class="cp">, note = </span><span
class="s">"..."</span><span class="cp">)]</span>
+</pre></div>
+</div>
+<p>For example:</p>
<div class="highlight-rust notranslate"><div
class="highlight"><pre><span></span><span class="w"> </span><span
class="cp">#[deprecated(since = </span><span
class="s">"41.0.0"</span><span class="cp">, note = </span><span
class="s">"Use SessionStateBuilder"</span><span class="cp">)]</span>
<span class="w"> </span><span class="k">pub</span><span class="w">
</span><span class="k">fn</span><span class="w"> </span><span
class="nf">new_with_config_rt</span><span class="p">(</span><span
class="n">config</span><span class="p">:</span><span class="w"> </span><span
class="nc">SessionConfig</span><span class="p">,</span><span class="w">
</span><span class="n">runtime</span><span class="p">:</span><span class="w">
</span><span class="nc">Arc</span><span class="o"><</span><span [...]
</pre></div>
</div>
<p>Deprecated methods will remain in the codebase for a period of 6 major
versions or 6 months, whichever is longer, to provide users ample time to
transition away from them.</p>
<p>Please refer to <a class="reference external"
href="https://crates.io/crates/datafusion/versions";>DataFusion releases</a> to
plan ahead API migration</p>
+</section>
</section>
diff --git a/searchindex.js b/searchindex.js
index 0d29c39742..5c5b6bd9c6 100644
--- a/searchindex.js
+++ b/searchindex.js
@@ -1 +1 @@
-Search.setIndex({"alltitles": {"!=": [[48, "op-neq"]], "!~": [[48,
"op-re-not-match"]], "!~*": [[48, "op-re-not-match-i"]], "!~~": [[48, "id18"]],
"!~~*": [[48, "id19"]], "#": [[48, "op-bit-xor"]], "%": [[48, "op-modulo"]],
"&": [[48, "op-bit-and"]], "(relation, name) tuples in logical fields and
logical columns are unique": [[9,
"relation-name-tuples-in-logical-fields-and-logical-columns-are-unique"]], "*":
[[48, "op-multiply"]], "+": [[48, "op-plus"]], "-": [[48, "op-minus"]], "/":
[[4 [...]
\ No newline at end of file
+Search.setIndex({"alltitles": {"!=": [[48, "op-neq"]], "!~": [[48,
"op-re-not-match"]], "!~*": [[48, "op-re-not-match-i"]], "!~~": [[48, "id18"]],
"!~~*": [[48, "id19"]], "#": [[48, "op-bit-xor"]], "%": [[48, "op-modulo"]],
"&": [[48, "op-bit-and"]], "(relation, name) tuples in logical fields and
logical columns are unique": [[9,
"relation-name-tuples-in-logical-fields-and-logical-columns-are-unique"]], "*":
[[48, "op-multiply"]], "+": [[48, "op-plus"]], "-": [[48, "op-minus"]], "/":
[[4 [...]
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
