From d4a35b207c9bf7b7b7f3925cce6fc3c17d1ae0f5 Mon Sep 17 00:00:00 2001 From: SteveLauC Date: Sun, 26 Nov 2023 01:07:17 +0800 Subject: [PATCH] docs: document how to remove/deprecate an interface (#2209) --- CONVENTIONS.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index eac629c334..e461b13b24 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -100,3 +100,20 @@ type or mutability that way. [`cast()`]: https://doc.rust-lang.org/std/primitive.pointer.html#method.cast [`cast_mut()`]: https://doc.rust-lang.org/std/primitive.pointer.html#method.cast_mut [`cast_const()`]: https://doc.rust-lang.org/std/primitive.pointer.html#method.cast_const + +## Remove/deprecate an interface + +In Nix, if we want to remove something, we don't do it immediately, instead, we +deprecate it for at least one release before removing it. + +To deprecate an interface, put the following attribute on the top of it: + +``` +#[deprecated(since = "", note = "")] +``` + +`` is the version where this interface will be deprecated, in most +cases, it will be the version of the next release. And a user-friendly note +should be added. Normally, there should be a new interface that will replace +the old one, so a note should be something like: " should be +used instead".