Add deprecation / API removal policy

README.md

@@ -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
+first version they were deprecated in, as well as what new API to use instead.
+
+```rust
+#[deprecated(since = "51.0.0", note = "Use `date_part` instead")]
+```
+
+Deprecated APIs will be kept for at least one major release after they were
+deprecated. For example, an API deprecated in `51.3.0` will not be removed until
+at least `53.0.0`. Given the planned release schedule, this is typically between
+3 and 6 months.
+
 ## Related Projects
 
 There are several related crates in different repositories

arrow/README.md

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

parquet/README.md

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