From c5160f149287ea1c5fc0fad6438511aed2d06685 Mon Sep 17 00:00:00 2001 From: Rain Date: Tue, 14 Nov 2023 14:43:49 -0800 Subject: [PATCH] [site] add section on making behavior changes This is long overdue, and we're going to try and make a couple of behavior changes soon. --- site/src/book/stability.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/site/src/book/stability.md b/site/src/book/stability.md index 0aaff33e309..7f7a7535910 100644 --- a/site/src/book/stability.md +++ b/site/src/book/stability.md @@ -12,9 +12,32 @@ The cargo-nextest binary follows [semantic versioning](https://semver.org/), whe [Experimental features](experimental-features.md) are not part of the public API. They may change or be removed in a patch release. -Within a version series, the public API will be append-only. New options or keys may be added, but existing keys will continue to be as they were. Existing options may be deprecated but will not be removed within a version series. +Within a version series, the public API will be append-only. New options or keys may be added, but +existing keys will continue to be as they were. Existing options may be deprecated but will not be +removed within a version series, except via the policy listed in [Making behavior changes](#making-behavior-changes). -The public API does _not_ include human-readable output generated by nextest, or in general anything printed to stderr. +The public API does _not_ include human-readable output generated by nextest, or in general anything +printed to stderr. + +### Making behavior changes + +In general, the meaning of options will not change and functionality will not be removed from +cargo-nextest within a version series. + +However, in some cases, we may need to make behavior changes to fix a bug or security issue. These +sorts of changes will be made based on standard semantic versioning rules: bugs will be fixed in +patch releases, with due consideration given to existing use cases. + +We may also need to make behavior changes to address what we consider to be major user interface +deficiencies. **This will not be done lightly:** the maintainers of nextest understand the +importance of stable, dependable CLI interfaces. + +In those cases, we will follow the following procedure: + +1. On the nextest issue tracker, an issue will be filed under the [*behavior-change* label](https://github.com/nextest-rs/nextest/issues?q=is%3Aopen+label%3Abehavior-change+sort%3Aupdated-desc). This issue will outline the motivation, and be used for coordination and feedback. +2. The behavior will be marked as deprecated and a warning will be provided within the CLI. If applicable, an alternative will be provided in the warning message. If there is no alternative, a configuration option and/or environment variable will be provided to silence the warning. +3. A timeline to change the behavior will be provided. The timeline will be at least 3 months long to provide ample time for users to adapt to the new behavior. +4. After that time has elapsed, the behavior will be changed in the following version of nextest. ## Libraries