doc(ADR): deprecated functions do not have examples (#5932)

Author: coryan

doc/adr/2021-03-01-deprecated-functions-do-not-have-examples.md

@@ -0,0 +1,24 @@
+**Title**: Deprecated functions do not have examples.
+
+**Status**: accepted
+
+**Context**: we write examples for all important functions, typically the ones
+that result in one or more RPCs. From time to time we need to deprecate a
+function, maybe because the function has a serious defect that cannot be
+resolved without changing its API, or because the function represents an
+experiment that "failed", or because we found a better way to do things.
+
+**Decision**: when we deprecate a function we will remove the examples to that
+function. If the function is being replaced, we will reference the replacement
+in the "Examples" paragraph. If the function is being removed, we will simply
+remove the examples before the function itself. Unit tests and integration
+tests are preserved. While a function might be deprecated, it is expected to
+work.
+
+**Consequences**: customers will be directed to the improved replacement,
+customers will not be misguided by examples that point to a deprecated approach.
+Developers of `google-cloud-cpp` will have fewer examples to maintain. Customers
+that cannot migrate to the new approach will not find examples of the approach
+they are currently using, this is mitigated by (a) they already are using the
+old approach, and (b) they can find the examples in the documentation
+accompanying old releases.