From 44067135651d448556ff4aef8f71e6bb298e69d6 Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Tue, 6 Apr 2021 12:22:39 +0200 Subject: [PATCH 1/4] Document how to rename properties --- docs/configuration.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/configuration.md b/docs/configuration.md index 9364ac8ee29..bec9cdd49e0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -84,3 +84,11 @@ In addition to environment variables, other ways of defining configuration also case and replacing underscores with hyphens or periods. For example: system property `splunk.context.server-timing.enabled` is equivalent to environment variable `SPLUNK_CONTEXT_SERVER_TIMING_ENABLED`. + +## Making backwards incompatible changes + +Whenever a configuration variable changes its name a GDI project MUST support both +old and new names for at least one release. When it is detected that a user +uses the old configuration variable a warning SHOULD be logged: the warning +SHOULD state that the old variable is deprecated, the new one should be used instead, +and that the old one will be removed in the next release (if applicable). From 31aac6e5df89e864340df83558160d29eaa6243a Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Tue, 6 Apr 2021 13:29:37 +0200 Subject: [PATCH 2/4] Code review comments --- docs/configuration.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index bec9cdd49e0..d0904ad3be3 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -87,8 +87,12 @@ In addition to environment variables, other ways of defining configuration also ## Making backwards incompatible changes -Whenever a configuration variable changes its name a GDI project MUST support both -old and new names for at least one release. When it is detected that a user -uses the old configuration variable a warning SHOULD be logged: the warning -SHOULD state that the old variable is deprecated, the new one should be used instead, -and that the old one will be removed in the next release (if applicable). +Whenever a configuration variable changes its name a stable GDI project MUST +support both old and new names for at least one release. GDI projects that are +not yet stable SHOULD follow this rule, but they are not required to. + +When it is detected that a user uses the old configuration variable a warning +SHOULD be logged: the warning SHOULD state that the old variable is deprecated, +the new one should be used instead, and that the old one will be removed in the +next major release (not stable GDI projects MAY remove deprecated features in any +future release). From 4e19111df36637ddebe1446f33c9e370b76eba4b Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Tue, 6 Apr 2021 13:33:23 +0200 Subject: [PATCH 3/4] Code review comments --- docs/configuration.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index d0904ad3be3..d3cf38946ea 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -87,9 +87,11 @@ In addition to environment variables, other ways of defining configuration also ## Making backwards incompatible changes -Whenever a configuration variable changes its name a stable GDI project MUST -support both old and new names for at least one release. GDI projects that are -not yet stable SHOULD follow this rule, but they are not required to. +Whenever a configuration variable changes its name a stable GDI project +(version >= 1.0) MUST support both old and new names for at least one release. +The old configuration variable MUST NOT be removed in a minor release. +GDI projects that are not yet stable (version < 1.0) SHOULD follow this rule, +but they are not required to. When it is detected that a user uses the old configuration variable a warning SHOULD be logged: the warning SHOULD state that the old variable is deprecated, From 89467e9bc37fdb6415ca51b1f2147d267d38558d Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Tue, 6 Apr 2021 18:15:12 +0200 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: John Watson --- docs/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index d3cf38946ea..cbb5a717111 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -87,8 +87,8 @@ In addition to environment variables, other ways of defining configuration also ## Making backwards incompatible changes -Whenever a configuration variable changes its name a stable GDI project -(version >= 1.0) MUST support both old and new names for at least one release. +Whenever a configuration variable changes its name, a stable GDI project +(version >= 1.0) MUST support both old and new names until the next major release is done. The old configuration variable MUST NOT be removed in a minor release. GDI projects that are not yet stable (version < 1.0) SHOULD follow this rule, but they are not required to.