Create formal deprecation process

[htuch]

As suggested by @RomanDzhabarov, we should have a clearer way to track deprecated features (e.g. #994, #979). We agreed to add a DEPERECATED.md to track deprecations in the Envoy source root.

In addition, maybe we can consider flag protection of deprecated features so we can turn them off easily on the CLI and validate behavior. This would be easy with gflags, not sure about using tclap.

[htuch]

Another idea: have a log().warning requirement to appear once only the first time a deprecated feature is used.

[htuch]

Also, require commit messages to mention deprecation.

[jwfang]

#988 DEPRECATED http_codec_options config.

[RomanDzhabarov]

covered by #1019 and #1026

[RomanDzhabarov]

There is one open question on whether we should have soft deprecation in place.

"I'm still wondering about flag protection for deprecated features. Not to restart the tclap vs. gflags discussion, but with gflags it's fairly cheap to add CLI startup flags to enable/disable deprecated features, it might allow us to perform a softer deprecation. WDYT?"

"Having soft deprecation would mean for us to keep all of the if/else (sometimes messy) code around forever.
But obviously, it eases migration to a newer version. Let's bring this up once mattklein123 back if he has strong opinion on those options."

[htuch]

I'm not advocating we keep flags around forever. Instead, we can flag protect the deprecated feature in master up to the next release X, turn the flag off at release X, and then remove the flag and deprecated code at X+1.

[mattklein123]

IMO it's not worth the effort to have CLI options to control the deprecation. It will just lead to more tests needing to be written and more code complexity during the deprecation interval. IMO it's simpler to just have tests for both paths, then just nuke the old code and tests when we snap the next release as one of the first work items. I think we should start with the simple approach, and then if it becomes clear that CLI options are necessary for some reason we can do that? I will try to codify all of this in the contributing guide this week.