Skip to content

Commit

Permalink
[chore] Clarify allowed changes to struct field tags in VERSIONING.md (
Browse files Browse the repository at this point in the history
…open-telemetry#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
open-telemetry#12191.
  • Loading branch information
evan-bradley authored Jan 28, 2025
1 parent 96ba827 commit f0c7a8b
Showing 1 changed file with 5 additions and 1 deletion.
6 changes: 5 additions & 1 deletion VERSIONING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down

0 comments on commit f0c7a8b

Please sign in to comment.