[chore] Clarify allowed changes to struct field tags in VERSIONING.md (#12190)

#### Description

Add wording that allows us to update struct field tags if changes to the
tags doesn't change the values of fields in the struct during
serialization/deserialization.

This will allow us to add `omitempty` to fields on structs in stable
packages. Adding this tag will cause fields which have zero values to
not be written when marshaling into YAML, but there is no functional
difference since missing fields during unmarshaling simply leaves a
struct field with a zero value.

Related to
https://github.com/open-telemetry/opentelemetry-collector/issues/12191.
This commit is contained in:
Evan Bradley 2025-01-28 10:20:06 -05:00 committed by GitHub
parent 96ba827bb0
commit f0c7a8b507
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 5 additions and 1 deletions

View File

@ -81,7 +81,11 @@ may become valid after a change to the validation rules.
The following are explicitly considered to be breaking changes:
* **Modifying struct tags related to serialization**. Struct tags used to configure serialization mechanisms (`yaml:`,
`mapstructure:`, etc) are part of the structure definition and must maintain compatibility to the same extent as the
structure.
structure. However, changes are allowed when tag modifications produce a
functionally-equivalent result when serializing or deserializing the structure.
For example, adding a tag to a field so it will not be emitted during serialization
if it has a default value would not alter its value if the serialized representation
were again deserialized, so such a change would be permitted.
* **Making validation rules more strict**. A valid configuration struct as defined by its `Validate` method return value
must continue to be valid after a change to the validation rules, except when the configuration struct would cause an error
on its intended usage (e.g. when calling a method or when passed to any method or function in any module under opentelemetry-collector).