governance: changing deprecation policy from one release to two. (#5737)

This brings deprecation window from between 0-3 months to 3-6 months. Updating tools / docs accordingly.

Note the deprecation script can be skipped when we cut the next release because of this.
Also fixing up the deprecation script to handle (date)s and (pending)

Docs Changes: n/a
Release Notes: inline
Fixes #5694

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

CONTRIBUTING.md

@@ -29,10 +29,10 @@ maximize the chances of your PR being merged.
   etc.), and CLI switches. We will also try to not change behavioral semantics
   (e.g., HTTP header processing order), though this is harder to outright
   guarantee.
-* We reserve the right to deprecate configuration, and at the beginning of the following release
-  cycle remove the deprecated configuration. For example, all deprecations between 1.3.0 and
-  1.4.0 will be deleted soon AFTER 1.4.0 is tagged and released (at the beginning of the 1.5.0
-  release cycle).
+* We reserve the right to deprecate configuration, after two release cycles. For example, all
+  deprecations between 1.3.0 and 1.4.0 will be deleted soon AFTER 1.5.0 is tagged and released
+  (at the beginning of the 1.6.0 release cycle). This results in a three to six month window for
+  migrating from deprecated code paths to new code paths.
 * This policy means that organizations deploying master should have some time to get ready for
   breaking changes, but we make no guarantees about the length of time.
 * The breaking change policy also applies to source level extensions (e.g., filters). Code that
@@ -63,8 +63,9 @@ maximize the chances of your PR being merged.
 * For configuration deprecations that are not covered by the above semantic
   replacement policy, any deprecation will only take place after
   community consultation on mailing lists, Slack and GitHub, over the period of
-  a minimum of two Envoy release cycles (~6 months). This includes where a
-  feature is outright deleted with no replacement.
+  a minimum of two Envoy release cycles (~6 months). Cases where a feature is
+  outright deleted with no replacement will get an additional two Envoy release
+  cycles (~12 months) before removal.
 
 # Release cadence
 

GOVERNANCE.md

@@ -97,7 +97,7 @@
   the same time, also add a new empty "pending" section to the [release
   notes](docs/root/intro/version_history.rst) and to [DEPRECATED.md](DEPRECATED.md) for the
   following version. E.g., "1.7.0 (pending)".
-* Run the deprecate_versions.py script (e.g. `sh tools/deprecate_version/deprecate_version.sh 1.9.0 1.10.0`)
+* Run the deprecate_versions.py script (e.g. `sh tools/deprecate_version/deprecate_version.sh 1.8.0 1.10.0`)
   to file tracking issues for code which can be removed.
 
 ## When does a maintainer lose maintainer status

docs/root/intro/version_history.rst

@@ -18,6 +18,7 @@ Version history
   <envoy_api_field_config.filter.http.ext_authz.v2.AuthorizationResponse.allowed_client_headers>` and :ref:`upstream headers
   <envoy_api_field_config.filter.http.ext_authz.v2.AuthorizationResponse.allowed_upstream_headers>` replaces the previous *allowed_authorization_headers* object.
   All the control header lists now support :ref:`string matcher <envoy_api_msg_type.matcher.StringMatcher>` instead of standard string.
+* governance: extending Envoy deprecation policy from 1 release (0-3 months) to 2 releases (3-6 months).
 * http: added new grpc_http1_reverse_bridge filter for converting gRPC requests into HTTP/1.1 requests.
 * outlier_detection: added support for :ref:`outlier detection event protobuf-based logging <arch_overview_outlier_detection_logging>`.
 * mysql: added a MySQL proxy filter that is capable of parsing SQL queries over MySQL wire protocol. Refer to ::ref:`MySQL proxy<config_network_filters_mysql_proxy>` for more details.

tools/deprecate_version/deprecate_version.py

@@ -5,11 +5,11 @@
 #
 # Direct usage (not recommended):
 #
-# python tools/deprecate_version/deprecate_version.py <deprecate for version> <deprecate by version>
+# python tools/deprecate_version/deprecate_version.py <2 releases ago> <current release>
 #
 # e.g
 #
-#  python tools/deprecate_version/deprecate_version.py 1.6.0 1.7.0
+#  python tools/deprecate_version/deprecate_version.py 1.5.0 1.7.0
 #
 # A GitHub access token must be set in GH_ACCESS_TOKEN. To create one, go to
 # Settings -> Developer settings -> Personal access tokens in GitHub and create
@@ -59,7 +59,7 @@ def GetHistory():
   history = defaultdict(set)
   for commit, lines in repo.blame('HEAD', 'DEPRECATED.md'):
     for line in lines:
-      sr = re.match('## Version (.*)', line)
+      sr = re.match('## Version (.*) \(.*\)', line)
       if sr:
         version = sr.group(1)
         continue