From cb06b7956cf43aa3aafea1c9f977fd3e27764e3e Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Thu, 12 Oct 2023 10:42:35 -0500 Subject: [PATCH] Add versioning policy to documentation (#7923) Most of the content adapted from https://github.com/astral-sh/ruff/discussions/6998 --- docs/versioning.md | 61 ++++++++++++++++++++++++++++++++++++++ scripts/generate_mkdocs.py | 1 + 2 files changed, 62 insertions(+) create mode 100644 docs/versioning.md diff --git a/docs/versioning.md b/docs/versioning.md new file mode 100644 index 0000000000..c049983904 --- /dev/null +++ b/docs/versioning.md @@ -0,0 +1,61 @@ +# Versioning + +Ruff uses a custom versioning scheme that uses the **minor** version number for breaking changes and the **patch** version number for bug fixes. Ruff does not yet have a stable API; once Ruff's API is stable, the **major** version number and semantic versioning will be used. + +## Version changes + +**Minor** version increases will occur when: + +- A deprecated option or feature is removed +- Configuration changes in a backwards incompatible way + - This _may_ occur in minor version changes until `1.0.0`, however it should generally be avoided. +- A rule is promoted to stable +- Support for a new file type is promoted to stable +- Support for an end-of-life Python version is dropped +- The behavior of a stable rule is changed + - Does not include bug fixes that follow the original intent of the rule +- Stable rules are added to the default set +- Stable rules are removed from the default set +- A safe fix for a rule is promoted to stable + +**Patch** version increases will occur when: + +- Bugs are fixed, _including behavior changes that fix bugs_ +- An unsafe fix for a rule is added +- A safe fix for a rule is added in preview +- A fix’s applicability is demoted +- A new configuration option is added +- A rule is added in preview +- The behavior of a preview rule is changed +- Support for a new Python version is added +- Support for a new file type is added in preview +- An option or feature is deprecated + +## Preview mode + +A preview mode is available to enable new, unstable rules and features e.g. support for a new file type. + +The preview mode is intended to help us collect community feedback and gain confidence that changes are a net-benefit. + +The preview mode is _not_ intended to gate access to work that is incomplete or features that we are _likely to remove._ However, **we reserve the right to make changes to _any_ behavior gated by the mode** including the removal of preview features or rules. + +## Rule stabilization + +When modifying or adding rules, we use the following guidelines: + +- New rules are always be added in a preview mode +- New rules remain in preview mode for at least one minor release before being promoted to stable + - If added in a patch release i.e. `0.6.1` then a rule are not be eligible for stability until `0.8.0` +- Stable rule behavior are not changed significantly in patch versions +- Promotion of rules to stable may be delayed in order to “batch” them into a single minor release +- Not all rules in preview need to be promoted in a given minor release + +## Fix stabilization + +Fixes have three applicability levels: + +- **Display**: Never applied, just displayed. +- **Unsafe**: Can be applied with explicit opt-in. +- **Safe**: Can be applied automatically. + +Fixes for rules may be introduced at a lower applicability then promoted to a higher applicability. Reducing the applicability of a fix is not a breaking change. The applicability of a given fix may change when the preview mode is enabled. diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py index fca6856809..0c7972b684 100644 --- a/scripts/generate_mkdocs.py +++ b/scripts/generate_mkdocs.py @@ -29,6 +29,7 @@ SECTIONS: list[Section] = [ Section("Rules", "rules.md", generated=True), Section("Settings", "settings.md", generated=True), Section("Editor Integrations", "editor-integrations.md", generated=False), + Section("Versioning", "versioning.md", generated=False), Section("FAQ", "faq.md", generated=False), Section("Contributing", "contributing.md", generated=True), ]