From 4d0bc49eb5b7f59da537847e8388e1b35c601e7e Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Tue, 28 Apr 2020 15:01:20 -0400 Subject: [PATCH 1/5] docs: updating runtime guard policy Signed-off-by: Alyssa Wilk --- CONTRIBUTING.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2b8723439638..5101b8d1e43e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -125,10 +125,13 @@ versioning guidelines: # Runtime guarding -Some high risk changes in Envoy are deemed worthy of runtime guarding. Instead of just replacing +Some changes in Envoy are deemed worthy of runtime guarding. Instead of just replacing old code with new code, both code paths are supported for between one Envoy release (if it is guarded due to performance concerns) and a full deprecation cycle (if it is a high risk behavioral -change). +change). Generally as a community we try to guard both high risk changes (major +refactors such as replacing Envoy's buffer implementation) and most user-visible +non-config-guarded changes to HTTP processing (for example additions or changes to HTTP headers or +how HTTP is serialized out). The canonical way to runtime guard a feature is ``` @@ -156,7 +159,7 @@ time. Runtime guarded features may either set true (running the new code by default) in the initial PR, after a testing interval, or during the next release cycle, at the PR author's and reviewing maintainer's discretion. Generally all runtime guarded features will be set true when a -release is cut, and the old code path will be deprecated at that time. Runtime features +release is cut, and the old code path will be deprecated after six months. Runtime features are set true by default by inclusion in [source/common/runtime/runtime_features.h](https://github.com/envoyproxy/envoy/blob/master/source/common/runtime/runtime_features.h) From 924f5461569c882464deb5c3cb88bbc3dbc9ecc2 Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Tue, 28 Apr 2020 15:13:17 -0400 Subject: [PATCH 2/5] not all changes are created equal Signed-off-by: Alyssa Wilk --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5101b8d1e43e..2aedd8bf054d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -159,8 +159,9 @@ time. Runtime guarded features may either set true (running the new code by default) in the initial PR, after a testing interval, or during the next release cycle, at the PR author's and reviewing maintainer's discretion. Generally all runtime guarded features will be set true when a -release is cut, and the old code path will be deprecated after six months. Runtime features -are set true by default by inclusion in +release is cut. Old code paths for refactors can be cleaned up after a release and there has been +some production run time. Old code for behavioral changes will be deprecated after six months. +Runtime features are set true by default by inclusion in [source/common/runtime/runtime_features.h](https://github.com/envoyproxy/envoy/blob/master/source/common/runtime/runtime_features.h) There are four suggested options for testing new runtime features: From 2f5a5daf1a56eefbe5fadb144ef4fdd2833123a7 Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Tue, 28 Apr 2020 16:50:46 -0400 Subject: [PATCH 3/5] reviewer comments Signed-off-by: Alyssa Wilk --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2aedd8bf054d..74e24a2f3cac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -130,8 +130,8 @@ old code with new code, both code paths are supported for between one Envoy rele guarded due to performance concerns) and a full deprecation cycle (if it is a high risk behavioral change). Generally as a community we try to guard both high risk changes (major refactors such as replacing Envoy's buffer implementation) and most user-visible -non-config-guarded changes to HTTP processing (for example additions or changes to HTTP headers or -how HTTP is serialized out). +non-config-guarded changes to protocol processing (for example additions or changes to HTTP headers or +how HTTP is serialized out) for non-alpha features. The canonical way to runtime guard a feature is ``` From d28eacfb9bc883d78882c4b646f9dc7ae0297a22 Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Wed, 29 Apr 2020 08:57:45 -0400 Subject: [PATCH 4/5] reviewer comments Signed-off-by: Alyssa Wilk --- CONTRIBUTING.md | 3 ++- PULL_REQUEST_TEMPLATE.md | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74e24a2f3cac..d45c293e6db7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -131,7 +131,8 @@ guarded due to performance concerns) and a full deprecation cycle (if it is a hi change). Generally as a community we try to guard both high risk changes (major refactors such as replacing Envoy's buffer implementation) and most user-visible non-config-guarded changes to protocol processing (for example additions or changes to HTTP headers or -how HTTP is serialized out) for non-alpha features. +how HTTP is serialized out) for non-alpha features. Feel free to tag @envoyproxy/maintainers +if you aren't sure if a given change merits runtime guarding. The canonical way to runtime guard a feature is ``` diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md index e16c81139d86..d72e0564dbf1 100644 --- a/PULL_REQUEST_TEMPLATE.md +++ b/PULL_REQUEST_TEMPLATE.md @@ -7,5 +7,6 @@ Risk Level: Testing: Docs Changes: Release Notes: +[Optional Runtime guard:] [Optional Fixes #Issue] [Optional Deprecated:] From b81cdf86d27cdb31753fcb196f90b90420663a51 Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Thu, 30 Apr 2020 10:21:38 -0400 Subject: [PATCH 5/5] reviewer comments Signed-off-by: Alyssa Wilk --- CONTRIBUTING.md | 2 +- PULL_REQUESTS.md | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d45c293e6db7..b89f748a9f4c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -131,7 +131,7 @@ guarded due to performance concerns) and a full deprecation cycle (if it is a hi change). Generally as a community we try to guard both high risk changes (major refactors such as replacing Envoy's buffer implementation) and most user-visible non-config-guarded changes to protocol processing (for example additions or changes to HTTP headers or -how HTTP is serialized out) for non-alpha features. Feel free to tag @envoyproxy/maintainers +how HTTP is serialized out) for non-alpha features. Feel free to tag @envoyproxy/maintainers if you aren't sure if a given change merits runtime guarding. The canonical way to runtime guard a feature is diff --git a/PULL_REQUESTS.md b/PULL_REQUESTS.md index 0126cf073ea6..91211e3ff415 100644 --- a/PULL_REQUESTS.md +++ b/PULL_REQUESTS.md @@ -67,6 +67,16 @@ current version. Please include any relevant links. Each release note should be relevant subsystem in **alphabetical order** (see existing examples as a guide) and include links to relevant parts of the documentation. Thank you! Please write in N/A if there are no release notes. +### Runtime guard + +If this PR has a user-visible behavioral change, or otherwise falls under the +guidelines for runtime guarding in the [contributing doc](CONTRIBUTING.md.md) +it should have a runtime guard, which should be documented both in the release +notes and here in the PR description. + +For new feature additions guarded by configs, no-op refactors, docs changes etc. +this field can be disregarded and/or removed. + ### Issues If this PR fixes an outstanding issue, please add a line of the form: