From bf97671bc7291515a457ae851dab53a864a9d747 Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Mon, 7 Dec 2020 08:55:23 +0900 Subject: [PATCH] Document the policy about breaking change --- CONTRIBUTING.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d72c3ecc..1acc71d9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ With that in mind, the steps for adding a new API are: 4. Wait for CI to pass, fixing errors. 5. Wait for a merge! -### Test before you commit +## Test before you commit We have two automated tests running on [GitHub Actions](https://github.com/rust-lang/libc/actions): @@ -46,7 +46,23 @@ We have two automated tests running on [GitHub Actions](https://github.com/rust- 2. Style checker - `rustc ci/style.rs && ./style src` -### Releasing your change to crates.io +## Breaking change policy + +Sometimes an upstream adds a breaking change to their API e.g. removing outdated items, +changing the type signature, etc. And we probably should follow that change to build the +`libc` crate successfully. It's annoying to do the equivalent of semver-major versioning +for each such change. Instead, we mark the item as deprecated and do the actual change +after a certain period. The steps are: + +1. Add `#[deprecated(since = "", note="")]` attribute to the item. + - The `since` field should have a next version of `libc` + (e.g., if the current version is `0.2.1`, it should be `0.2.2`). + - The `note` field should have a reason to deprecate and a tracking issue to call for comments + (e.g., "We consider removing this as the upstream removed it. + If you're using it, please comment on #XXX"). +2. If we don't see any concerns for a while, do the change actually. + +## Releasing your change to crates.io Now that you've done the amazing job of landing your new API or your new platform in this crate, the next step is to get that sweet, sweet usage from