Skip to content

Commit

Permalink
docs: exempt converters from backwards compatibility guarantees (#6747)
Browse files Browse the repository at this point in the history
Converter code is not cheap to maintain, and in some cases can bring in
many dependencies that are otherwise unused, making project maintainance
more difficult.

This change explicitly marks converter code as exempt from backwards
compatibility guarntees, allowing its removal between minor versions if
a converter is no longer needed and maintainers don't want to wait for
the next major release to remove it.

The RFC for backwards compatibility guarantees is also updated to make
it clear that some functionality may opt out of backwards compatibility
guarantees, which includes the `convert` and `tools` commands.
  • Loading branch information
rfratto authored Mar 21, 2024
1 parent 514c541 commit 6554bf6
Show file tree
Hide file tree
Showing 2 changed files with 7 additions and 1 deletion.
2 changes: 2 additions & 0 deletions docs/rfcs/0008-backwards-compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,8 @@ It's impossible to guarantee that full backwards compatibility is achieved. Ther

- Other telemetry data: metrics, logs, and traces may change between releases. Only telemetry data which is used in official dashboards is protected under backwards compatibility.

- Tagged as exempt: functionality which is explicitly marked as exempt from backwards compatibility guarantees may include breaking changes or removal between minor releases.

### Avoiding major release burnout 

As a new major release implies a user must put extra effort into upgrading, it is possible to burn out users by releasing breaking changes too frequently. 
Expand Down
6 changes: 5 additions & 1 deletion docs/sources/flow/reference/cli/convert.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@ weight: 100

The `convert` command converts a supported configuration format to {{< param "PRODUCT_NAME" >}} River format.

{{< admonition type="caution" >}}
This command has no backward compatibility guarantees and may change or be removed between releases.
{{< /admonition >}}

## Usage

Usage:
Expand Down Expand Up @@ -113,4 +117,4 @@ flags with a space between each flag, for example `--extra-args="-enable-feature
If you have unsupported features in a Static mode source configuration, you will receive [errors][] when you convert to a Flow mode configuration. The converter will
also raise warnings for configuration options that may require your attention.

Refer to [Migrate from Grafana Agent Static to {{< param "PRODUCT_NAME" >}}]({{< relref "../../tasks/migrate/from-static/" >}}) for a detailed migration guide.
Refer to [Migrate from Grafana Agent Static to {{< param "PRODUCT_NAME" >}}]({{< relref "../../tasks/migrate/from-static/" >}}) for a detailed migration guide.

0 comments on commit 6554bf6

Please sign in to comment.