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

Add deprecation / API removal policy #6852

Merged
merged 7 commits into from
Dec 18, 2024
+29 −2
Merged

Add deprecation / API removal policy #6852

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
f724954
Add deprecation / API removal policy
alamb Dec 6, 2024
da4527b
Increase proposal to 2 releases
alamb Dec 7, 2024
01c6977
change from policy to guidelines, add flexibility
alamb Dec 12, 2024
9eee208
Merge remote-tracking branch 'apache/main' into alamb/deprecation_policy
alamb Dec 12, 2024
1f5bf65
prettier
alamb Dec 12, 2024
7632458
Merge remote-tracking branch 'apache/main' into alamb/deprecation_policy
alamb Dec 17, 2024
9fcc60c
Make instructions more actionable
alamb Dec 17, 2024
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
27 changes: 27 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,33 @@ versions approximately every 2 months.

[`object_store`]: https://crates.io/crates/object_store

### Deprecation Guidelines

Minor releases may deprecate, but not remove APIs. Deprecating APIs allows
downstream Rust programs to still compile, but generate compiler warnings. This
gives downstream crates time to migrate prior to API removal.

To deprecate an API:

- Mark the API as deprecated using `#[deprecated]` and specify the exact arrow-rs version in which it was deprecated
- Concisely describe the preferred API to help the user transition

The deprecated version is the next version which will be released (please
consult the list above). To mark the API as deprecated, use the
`#[deprecated(since = "...", note = "...")]` attribute.

Foe example

```rust
#[deprecated(since = "51.0.0", note = "Use `date_part` instead")]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

like in DF deprecation guidelines, it it obvious how a contributor should fill the since field? eg is this the version string from cargo.toml, or next major from that?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

like in DF deprecation guidelines,

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to do it in 9fcc60c

```

In general, deprecated APIs will remain in the codebase for at least two major releases after
they were deprecated (typically between 6 - 9 months later). For example, an API
deprecated in `51.3.0` can be removed in `54.0.0` (or later). Deprecated APIs
may be removed earlier or later than these guidelines at the discretion of the
maintainers.

## Related Projects

There are several related crates in different repositories
Expand Down
2 changes: 1 addition & 1 deletion arrow/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ This crate is tested with the latest stable version of Rust. We do not currently

The `arrow` crate follows the [SemVer standard] defined by Cargo and works well
within the Rust crate ecosystem. See the [repository README] for more details on
the release schedule and version.
the release schedule, version and deprecation policy.

[SemVer standard]: https://doc.rust-lang.org/cargo/reference/semver.html
[repository README]: https://github.com/apache/arrow-rs
Expand Down
2 changes: 1 addition & 1 deletion parquet/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ This crate is tested with the latest stable version of Rust. We do not currently

The `parquet` crate follows the [SemVer standard] defined by Cargo and works well
within the Rust crate ecosystem. See the [repository README] for more details on
the release schedule and version.
the release schedule, version and deprecation policy.

[semver standard]: https://doc.rust-lang.org/cargo/reference/semver.html
[repository readme]: https://github.com/apache/arrow-rs
Expand Down
Loading