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
Merged

Add deprecation / API removal policy #6852

Show file tree
Hide file tree
Changes from 2 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
18 changes: 18 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,24 @@ versions approximately every 2 months.

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

### Deprecation Policy

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

All deprecated APIs are marked using the `#[deprecated]` attribute with both the
Copy link
Member

Choose a reason for hiding this comment

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

#[deprecated(since="...", note="...")] to decrease chances of creating new deprecations with missing since attr? (see #6782)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Clarified in 9fcc60c

first version they were deprecated in, and what new API to use instead.

```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

```

Deprecated APIs will be kept for at least two major releases after they were
Copy link
Member

Choose a reason for hiding this comment

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

The PR initially started with 1, now it's 2. This is not unimportant. The less the better from code maint. perspective

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes, I agree it is an important distinction. Let's see if any consensus emerges

deprecated. For example, an API deprecated in `51.3.0` will not be removed until
at least `54.0.0`. Given the planned release schedule, this is typically between
alamb marked this conversation as resolved.
Show resolved Hide resolved
6 and 9 months.

## 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