From c5889c074e866389c9ae923bf13aa4bec16f1adf Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 14:44:49 +0000 Subject: [PATCH 1/2] docs: add a stability page for 1.0 1.0 freezes rule names, the config file, the command line and the VS Code ids, so users need to know what SemVer covers, what may still change in a minor version (messages, the LSP surface, Liquid), and how new rules, severities, formatter output and deprecations are handled without breaking a CI run that passed before. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012jSfzj1UNFUHV9YmmbjLg4 --- site/src/content/docs/reference/stability.md | 43 ++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 site/src/content/docs/reference/stability.md diff --git a/site/src/content/docs/reference/stability.md b/site/src/content/docs/reference/stability.md new file mode 100644 index 0000000..7519935 --- /dev/null +++ b/site/src/content/docs/reference/stability.md @@ -0,0 +1,43 @@ +--- +title: Stability +description: What Ruby Templates keeps stable from 1.0, what may change in any release, and how rules, the formatter and deprecations change between versions. +--- + +From 1.0.0 Ruby Templates follows [Semantic Versioning](https://semver.org). One version number covers the VS Code extension, the `ruby-templates` command (npm `@x-ror/ruby-templates`) and the language server inside them. A change that breaks anything listed under [Covered](#covered) needs a new major version, even when only one of the three is affected. + +## Covered + +- **Rule names and departments**: every `Department/Name` in the [rules](/vscode-ruby-templates/reference/rules/) and [diagnostics](/vscode-ruby-templates/reference/diagnostics/) references, `Syntax/*` and `Config/Invalid` included. A rule is not renamed, merged or removed in a minor version. +- **`.ruby-templates.toml`**: the tables, keys, options and values described under [configuration](/vscode-ruby-templates/reference/rules/#configuration), how files merge, and the defaults: which rules are on and the default value of every option. +- **The command line**: the `check` and `format` subcommands and their flags, the [exit codes](/vscode-ruby-templates/guides/command-line/#exit-codes), and the shape of each [`--format` output](/vscode-ruby-templates/guides/command-line/#ci): the `text` line format, the GitHub workflow commands, the JSON field names and types, and the SARIF 2.1.0 log structure. New JSON fields and SARIF properties may be added. +- **VS Code**: the ids of the [settings](/vscode-ruby-templates/guides/settings/), the [commands](/vscode-ruby-templates/guides/commands/) and the [languages](/vscode-ruby-templates/guides/file-types/). + +## Not covered + +These may change in any release: + +- The text of diagnostic messages, including the message part of a `text` line. Match on the rule, not the words. +- Which cases a rule reports, within its documented purpose: fixing false positives or catching more of the same problem is a fix. +- `--verbose` output. +- The language server protocol between the extension and its server: `initializationOptions`, custom requests and notifications such as `rubyTemplates/routes`, and `Diagnostic.data`. The server ships inside the extension, and other editors are not supported yet. +- Experimental features: [Liquid](/vscode-ruby-templates/guides/file-types/#liquid), and anything a page labels experimental. + +## Rules in minor versions + +A minor version may add rules, but a project that passes `ruby-templates check` and `format --check` keeps passing: + +- A new formatting rule is off by default. +- A new lint rule is off by default or reports at information severity, which never fails `check`. It may be turned on, or raised, in the next major version. +- A rule's severity may be lowered in a minor version, and raised only in a major one. + +## Formatter output + +In a minor version the formatter's output changes only to fix wrong output: output that changes how the page renders, that changes again when formatted a second time, or that contradicts the documented behaviour. Style changes wait for a major version. + +## Deprecations + +A setting, key, flag or rule is deprecated in at least one minor version before it is removed: it keeps working and reports a deprecation note. It is removed only in a major version. + +## Older versions and newer config + +A `.ruby-templates.toml` that uses a rule or key added in 1.N is reported as a problem (exit 1) by versions before 1.N. Pin `@x-ror/ruby-templates` in CI to a version that knows your config. From f049b4ccc2d8dae8d2cea8372d8403ac8c00e1f7 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 14:45:23 +0000 Subject: [PATCH 2/2] docs: say a department switch doesn't turn on new rules The audit's change that a department's enabled = true only restores rules that are on by default is approved, so the page can promise it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012jSfzj1UNFUHV9YmmbjLg4 --- site/src/content/docs/reference/stability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/content/docs/reference/stability.md b/site/src/content/docs/reference/stability.md index 7519935..a85b7ad 100644 --- a/site/src/content/docs/reference/stability.md +++ b/site/src/content/docs/reference/stability.md @@ -26,7 +26,7 @@ These may change in any release: A minor version may add rules, but a project that passes `ruby-templates check` and `format --check` keeps passing: -- A new formatting rule is off by default. +- A new formatting rule is off by default, and a department's `enabled = true` doesn't turn it on: only its own `enabled = true` does. - A new lint rule is off by default or reports at information severity, which never fails `check`. It may be turned on, or raised, in the next major version. - A rule's severity may be lowered in a minor version, and raised only in a major one.