From b8f4e199f6b4f92d9bfe3f2cee77727e12adda10 Mon Sep 17 00:00:00 2001 From: jane400 Date: Sun, 18 Aug 2024 18:05:21 +0200 Subject: [PATCH] feat: document deprecation policy --- libpaket/README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/libpaket/README.md b/libpaket/README.md index 526059f..4f0dbcf 100644 --- a/libpaket/README.md +++ b/libpaket/README.md @@ -10,6 +10,13 @@ This is an unofficial client to various DHL APIs, more specific the ones that th - app-driven parcel lockers (App-gesteuerte Packstation) +## Deprecation notice + +It's recommended that consumers of this crate are always tracking the latest version. If the upstream API changes too much or a better API here is created, there are two ways to mark a function or struct deprecated: + +- Soft deprecation/Crate API changes: The normal deprecation notice via `#[deprecated]` (see the [RFC#1270](https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md) or the [rust reference docs](https://doc.rust-lang.org/reference/attributes/diagnostics.html)). +- (Fatal) Upstream API Changes: The soft deprecation marked with `deny(deprecated)`, you can try to override this, but functions with a `LibraryResult` will always return `LibraryError::Deprecated`. (NOTE: `LibrarayError::APIChange` is reserved for the case where the API-change is unknown. Please upgrade to a or wait for a newer crate version.) + ## Examples In the examples error-handling is ignored for simplicity. You don’t want to do that.