Skip to content

Commit

Permalink
docs: document backwards compatibility (#140)
Browse files Browse the repository at this point in the history
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 <[email protected]>
Co-authored-by: Clayton Cornell <[email protected]>
(cherry picked from commit 38fd764)
  • Loading branch information
rfratto authored and grafanabot committed Apr 8, 2024
1 parent 1eef9b3 commit f6b2669
Showing 1 changed file with 39 additions and 0 deletions.
39 changes: 39 additions & 0 deletions docs/sources/introduction/backward-compatability.md
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit f6b2669

Please sign in to comment.