From f6b2669b4746ca4ead81cd60f9d8a95975cc2a19 Mon Sep 17 00:00:00 2001 From: Robert Fratto Date: Mon, 8 Apr 2024 11:03:07 -0400 Subject: [PATCH] docs: document backwards compatibility (#140) Document backwards compatability based on the grafana/agent backwards compatability [RFC]. Some changes have been made: * Major release burnout and LTS suppor for previous major releases is not mentioned. * "The scope of backwards compatability" has been removed from the backwards compatability list, as it is needlessly verbose and we may have forgotten an obvious exception. * The exceptions "undocumented behavior," "tagged as exempt," "other telemetry data," and "non-versioned network APIs" have been integrated elsewhere in the doc to keep the list of exceptions shorter. Despite the changes above, the intent is still the same: we strive wherever possible to maintain compatability for users between minor and patch releases. [RFC]: https://github.com/grafana/agent/blob/main/docs/rfcs/0008-backwards-compatibility.md Co-authored-by: Paulin Todev Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> (cherry picked from commit 38fd764794d65eb008304a573d4588b4df0d8636) --- .../introduction/backward-compatability.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/sources/introduction/backward-compatability.md diff --git a/docs/sources/introduction/backward-compatability.md b/docs/sources/introduction/backward-compatability.md new file mode 100644 index 0000000000..fce867577d --- /dev/null +++ b/docs/sources/introduction/backward-compatability.md @@ -0,0 +1,39 @@ +--- +canonical: https://grafana.com/docs/alloy/latest/introduction/backward-compatability/ +description: Grafana Alloy backward compatibility +menuTitle: Backward compatibility +title: Grafana Alloy backward compatibility +weight: 999 +--- + +# {{% param "FULL_PRODUCT_NAME" %}} backward compatibility + +{{< param "FULL_PRODUCT_NAME" >}} follows [semantic versioning][]. +{{< param "PRODUCT_NAME" >}} is stable, and we strive to maintain backward compatibility between minor and patch versions. + +Documented functionality that's released as _Generally available_ is covered by backward compatibility, including: + +* **User configuration**, including the {{< param "PRODUCT_NAME" >}} configuration syntax, the semantics of the configuration file, and the command-line interface. + +* **APIs**, for any network or code API released as v1.0.0 or later. + +* **Observability data used in official dashboards**, where the official set of dashboards are found in [the `alloy-mixin/` directory][alloy-mixin]. + +## Exceptions + +We strive to maintain backward compatibility, but there are situations that may arise that require a breaking change without a new major version: + +* **Security**: A security issue may arise that requires breaking compatibility. + +* **Legal requirements**: If we learn that exposed behavior violates a licensing or legal requirement, a breaking change may be required. + +* **Specification errors**: If a specification for a feature is found to be incomplete or inconsistent, fixing the specification may require a breaking change. + +* **Bugs**: If a bug is found that goes against the documented specification of that functionality, fixing the bug may require breaking compatibility for users who are relying on the incorrect behavior. + +* **Upstream changes**: Much of the functionality of {{< param "PRODUCT_NAME" >}} is built on top of other software, such as OpenTelemetry Collector and Prometheus. If upstream software breaks compatibility, we may need to reflect this in {{< param "PRODUCT_NAME" >}}. + +We try, whenever possible, to resolve these issues without breaking compatibility. + +[semantic versioning]: https://semver.org/ +[alloy-mixin]: https://github.com/grafana/alloy/tree/main/operations/alloy-mixin