From 2e5b2d460da87a6e56272ccc230d918ef25badff Mon Sep 17 00:00:00 2001 From: Robert Fratto Date: Mon, 8 Apr 2024 08:15:49 -0400 Subject: [PATCH 1/4] docs: document backwards compatability: 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 --- docs/sources/backwards-compatability.md | 39 +++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/sources/backwards-compatability.md diff --git a/docs/sources/backwards-compatability.md b/docs/sources/backwards-compatability.md new file mode 100644 index 0000000000..1d39ba0d9b --- /dev/null +++ b/docs/sources/backwards-compatability.md @@ -0,0 +1,39 @@ +--- +canonical: https://grafana.com/docs/alloy/latest/backwards-compatability/ +description: Grafana Alloy backwards compatibility +menuTitle: Backwards compatibility +title: Grafana Alloy backwards compatibility +weight: 950 +--- + +# {{% param "FULL_PRODUCT_NAME" %}} backwards compatibility + +{{< param "FULL_PRODUCT_NAME" >}} follows [semantic versioning][]. +This means that {{< param "PRODUCT_NAME" >}} is stable, and that we strive to maintain backwards compatibility between minor and patch versions. + +Functionality which is documented and released as _Generally available_ is covered by backwards compatibility, including: + +* **User configuration**, including the {{< param "PRODUCT_NAME" >}} configuration syntax, 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 backwards compatibility, but there are situations which 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 foudn 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 breaing 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 makes a breaks compatibility, we may need to reflect 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 From f639acd07932d70fb0c658cf9cb75f4edcd757ce Mon Sep 17 00:00:00 2001 From: Robert Fratto Date: Mon, 8 Apr 2024 09:19:03 -0400 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Paulin Todev --- docs/sources/backwards-compatability.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sources/backwards-compatability.md b/docs/sources/backwards-compatability.md index 1d39ba0d9b..4856512046 100644 --- a/docs/sources/backwards-compatability.md +++ b/docs/sources/backwards-compatability.md @@ -27,11 +27,11 @@ We strive to maintain backwards compatibility, but there are situations which ma * **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 foudn to be incomplete or inconsistent, fixing the specification may require a breaking change. +* **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 breaing compatibility for users who are relying on the incorrect behavior. +* **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 makes a breaks compatibility, we may need to reflect in {{< param "PRODUCT_NAME" >}}. +* **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. From f2bb42b2c8c3c903bf3ffd184154bcfaa9113993 Mon Sep 17 00:00:00 2001 From: Robert Fratto Date: Mon, 8 Apr 2024 10:50:13 -0400 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> --- docs/sources/backwards-compatability.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/sources/backwards-compatability.md b/docs/sources/backwards-compatability.md index 4856512046..768589478c 100644 --- a/docs/sources/backwards-compatability.md +++ b/docs/sources/backwards-compatability.md @@ -1,19 +1,19 @@ --- canonical: https://grafana.com/docs/alloy/latest/backwards-compatability/ -description: Grafana Alloy backwards compatibility -menuTitle: Backwards compatibility -title: Grafana Alloy backwards compatibility +description: Grafana Alloy backward compatibility +menuTitle: Backward compatibility +title: Grafana Alloy backward compatibility weight: 950 --- -# {{% param "FULL_PRODUCT_NAME" %}} backwards compatibility +# {{% param "FULL_PRODUCT_NAME" %}} backward compatibility {{< param "FULL_PRODUCT_NAME" >}} follows [semantic versioning][]. -This means that {{< param "PRODUCT_NAME" >}} is stable, and that we strive to maintain backwards compatibility between minor and patch versions. +{{< param "PRODUCT_NAME" >}} is stable, and we strive to maintain backward compatibility between minor and patch versions. -Functionality which is documented and released as _Generally available_ is covered by backwards compatibility, including: +Documented functionality that's released as _Generally available_ is covered by backward compatibility, including: -* **User configuration**, including the {{< param "PRODUCT_NAME" >}} configuration syntax, semantics of the configuration file, and the command-line interface. +* **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. @@ -21,7 +21,7 @@ Functionality which is documented and released as _Generally available_ is cover ## Exceptions -We strive to maintain backwards compatibility, but there are situations which may arise that require a breaking change without a new major version: +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. @@ -33,7 +33,7 @@ We strive to maintain backwards compatibility, but there are situations which ma * **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. +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 From 0348985e182d3cc5eb921f8ae39cd55fbd8dc7e8 Mon Sep 17 00:00:00 2001 From: Robert Fratto Date: Mon, 8 Apr 2024 10:57:17 -0400 Subject: [PATCH 4/4] docs: move backward compatability to introduction section --- .../backward-compatability.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename docs/sources/{backwards-compatability.md => introduction/backward-compatability.md} (95%) diff --git a/docs/sources/backwards-compatability.md b/docs/sources/introduction/backward-compatability.md similarity index 95% rename from docs/sources/backwards-compatability.md rename to docs/sources/introduction/backward-compatability.md index 768589478c..fce867577d 100644 --- a/docs/sources/backwards-compatability.md +++ b/docs/sources/introduction/backward-compatability.md @@ -1,9 +1,9 @@ --- -canonical: https://grafana.com/docs/alloy/latest/backwards-compatability/ +canonical: https://grafana.com/docs/alloy/latest/introduction/backward-compatability/ description: Grafana Alloy backward compatibility menuTitle: Backward compatibility title: Grafana Alloy backward compatibility -weight: 950 +weight: 999 --- # {{% param "FULL_PRODUCT_NAME" %}} backward compatibility