From 5306e8f226486c05af8c77fa79f391c6b7fb7e28 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Wed, 30 Oct 2024 15:55:05 +0100 Subject: [PATCH] [chore][docs] Move configuration changes guidelines to component stability doc (#11572) #### Description Works towards #11553. Unifies information about component stability in a single document. #### Link to tracking issue Fixes #11571 --- docs/coding-guidelines.md | 42 +---------------------------------- docs/component-stability.md | 44 ++++++++++++++++++++++++++++++++++++- 2 files changed, 44 insertions(+), 42 deletions(-) diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md index f4f6a5b88f24..75faa968df2b 100644 --- a/docs/coding-guidelines.md +++ b/docs/coding-guidelines.md @@ -396,47 +396,7 @@ for the following situations. Note that these changes should still be recorded a #### Configuration changes -##### Alpha components - -Configuration for alpha components can be changed with minimal notice. Documenting them as part of the changelog is -sufficient. We still recommend giving users one or two minor versions' notice before breaking the configuration, such as -when removing or renaming a configuration option. Providing a migration path in the component's repository is NOT -required for alpha components, although it is still recommended. - -- when adding a new configuration option, components MAY mark the new option as required and are not required to provide - a reasonable default. -- when renaming a configuration option, components MAY treat the old name as an alias to the new one and log a WARN - level message in case the old option is being used. -- when removing a configuration option, components MAY keep the old option for a few minor releases and log a WARN level - message instructing users to remove the option. - -##### Beta components - -One of the requirements for a component to be marked as beta is to have its configuration options stabilized. Therefore, -backward incompatible changes should be rare events for beta components. Users of those components are not expecting to -have their Collector instances failing at startup because of a configuration change. When doing backward incompatible -changes, component owners should add the migration path to a place within the component's repository, linked from the -component's main README. This is to ensure that people using older instructions can understand how to migrate to the -latest version of the component. - -When adding a new required option: -- the option MUST come with a sensible default value - -When renaming or removing a configuration option: -- the option MUST be deprecated in one version -- a WARN level message should be logged, with a link to a place within the component's repository where the change is - documented and a migration path is provided -- the option MUST be kept for at least N+1 version and MAY be hidden behind a feature gate in N+2 -- the option and the WARN level message MUST NOT be removed earlier than N+2 or 6 months, whichever comes later - -Additionally, when removing an option: -- the option MAY be made non-operational already by the same version where it is deprecated - -##### Stable components - -Stable components MUST be compatible between minor versions unless critical security issues are found. In that case, the -component owner MUST provide a migration path and a reasonable time frame for users to upgrade. The same rules from beta -components apply to stable when it comes to configuration changes. +See [docs/component-stability.md](component-stability.md) for more information on how to handle configuration changes. ### Specification Tracking diff --git a/docs/component-stability.md b/docs/component-stability.md index ba259c3aa7c6..3510e80eecc5 100644 --- a/docs/component-stability.md +++ b/docs/component-stability.md @@ -14,16 +14,58 @@ Not all pieces of the component are in place yet and it might not be available a ### Alpha -The component is ready to be used for limited non-critical workloads and the authors of this component would welcome your feedback. Bugs and performance problems should be reported, but component owners might not work on them right away. The configuration options might change often without backwards compatibility guarantees. +The component is ready to be used for limited non-critical workloads and the authors of this component would welcome your feedback. Bugs and performance problems should be reported, but component owners might not work on them right away. + +#### Configuration changes + +Configuration for alpha components can be changed with minimal notice. Documenting them as part of the changelog is +sufficient. We still recommend giving users one or two minor versions' notice before breaking the configuration, such as +when removing or renaming a configuration option. Providing a migration path in the component's repository is NOT +required for alpha components, although it is still recommended. + +- when adding a new configuration option, components MAY mark the new option as required and are not required to provide + a reasonable default. +- when renaming a configuration option, components MAY treat the old name as an alias to the new one and log a WARN + level message in case the old option is being used. +- when removing a configuration option, components MAY keep the old option for a few minor releases and log a WARN level + message instructing users to remove the option. + ### Beta Same as Alpha, but the configuration options are deemed stable. While there might be breaking changes between releases, component owners should try to minimize them. A component at this stage is expected to have had exposure to non-critical production workloads already during its **Alpha** phase, making it suitable for broader usage. +#### Configuration changes + +Backward incompatible changes should be rare events for beta components. Users of those components are not expecting to +have their Collector instances failing at startup because of a configuration change. When doing backward incompatible +changes, component owners should add the migration path to a place within the component's repository, linked from the +component's main README. This is to ensure that people using older instructions can understand how to migrate to the +latest version of the component. + +When adding a new required option: +- the option MUST come with a sensible default value + +When renaming or removing a configuration option: +- the option MUST be deprecated in one version +- a WARN level message should be logged, with a link to a place within the component's repository where the change is + documented and a migration path is provided +- the option MUST be kept for at least N+1 version and MAY be hidden behind a feature gate in N+2 +- the option and the WARN level message MUST NOT be removed earlier than N+2 or 6 months, whichever comes later + +Additionally, when removing an option: +- the option MAY be made non-operational already by the same version where it is deprecated + ### Stable The component is ready for general availability. Bugs and performance problems should be reported and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output are not expected to happen without prior notice, unless under special circumstances. +#### Configuration changes + +Stable components MUST be compatible between minor versions unless critical security issues are found. In that case, the +component owner MUST provide a migration path and a reasonable time frame for users to upgrade. The same rules from beta +components apply to stable when it comes to configuration changes. + ### Deprecated The component is planned to be removed in a future version and no further support will be provided. Note that new issues will likely not be worked on. When a component enters "deprecated" mode, it is expected to exist for at least two minor releases. See the component's readme file for more details on when a component will cease to exist.