Add deprecation notes in documentation (jaegertracing#2909)

CONTRIBUTING.md

@@ -172,3 +172,32 @@ Before merging a PR make sure:
 
 Merge the PR by using "Squash and merge" option on Github. Avoid creating merge commits.
 After the merge make sure referenced issues were closed.
+
+## Deprecating CLI Flags
+
+* If a flag is deprecated in release N, it can be removed in release N+2 or three months later, whichever is later.
+* When adding a (deprecated) prefix to the flags, indicate via a deprecation message that the flag could be removed in the future. For example:
+  ```
+  (deprecated, will be removed after 2020-03-15 or in release v1.19.0, whichever is later)
+  ```
+* At the top of the file where the flag name is defined, add a constant and a comment, e.g.
+  ```
+  // TODO deprecated flag to be removed
+  healthCheckHTTPPortWarning = "(deprecated, will be removed after 2020-03-15 or in release v1.19.0, whichever is later)"
+  ```
+* Use that constant as the prefix to the help text, e.g.
+  ```
+  flagSet.Int(healthCheckHTTPPort, 0, healthCheckHTTPPortWarning+" see --"+adminHTTPHostPort)
+  ```
+* When parsing a deprecated flag into config, log a warning with the same deprecation message
+* Take care of deprecated flags in `initFromViper` functions, do not pass them to business functions.
+
+### Removing Deprecated CLI Flags
+* Ensure all references to the flag's variables have been removed in code.
+* Ensure a "Breaking Changes" entry is added in the [CHANGELOG](./CHANGELOG.md) indicating which CLI flag
+is being removed and which CLI flag should be used in favor of this removed flag.
+
+For example:
+```
+* Remove deprecated flags `--old-flag`, please use `--new-flag` ([#1234](<pull-request URL>), [@myusername](https://github.com/myusername))
+```

README.md

@@ -92,6 +92,23 @@ using Zipkin libraries, you do not have to rewrite all that code. Jaeger provide
 by accepting spans in Zipkin formats (Thrift or JSON v1/v2) over HTTP. Switching from Zipkin backend is just a matter
 of routing the traffic from Zipkin libraries to the Jaeger backend.
 
+## Version Compatibility Guarantees
+
+Occasionally, CLI flags can be deprecated due to, for example, usability improvements or new functionality.
+In such situations, developers introducing the deprecation are required to follow [these guidelines](./CONTRIBUTING.md#deprecating-cli-flags).
+
+In short, for a deprecated CLI flag, you should expect to see the following message in the `--help` documentation:
+```
+(deprecated, will be removed after yyyy-mm-dd or in release vX.Y.Z, whichever is later)
+```
+
+A grace period of at least **3 months** or **two minor version bumps** (whichever is later) from the first release
+containing the deprecation notice will be provided before the deprecated CLI flag _can_ be deleted.
+
+For example, consider a scenario where v1.28.0 is released on 01-Jun-2021 containing a deprecation notice for a CLI flag.
+This flag will remain in a deprecated state until the later of 01-Sep-2021 or v1.30.0 where it _can_ be removed on or after either of those events.
+It may remain deprecated for longer than the aforementioned grace period.
+
 ## Related Repositories
 
 ### Documentation