Add deprecation section to webrtc style guide

No-Presubmit: True
No-Try: True
Bug: webrtc:12484
Change-Id: I800926c8e8c79344fc8034d3fbd452d11d7b301a
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/208405
Commit-Queue: Danil Chapovalov <danilchap@webrtc.org>
Reviewed-by: Harald Alvestrand <hta@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#33315}

PRESUBMIT.py

@@ -157,7 +157,7 @@ API_CHANGE_MSG = """
 You seem to be changing native API header files. Please make sure that you:
   1. Make compatible changes that don't break existing clients. Usually
      this is done by keeping the existing method signatures unchanged.
-  2. Mark the old stuff as deprecated (see RTC_DEPRECATED macro).
+  2. Mark the old stuff as deprecated (use the ABSL_DEPRECATED macro).
   3. Create a timeline and plan for when the deprecated stuff will be
      removed. (The amount of time we give users to change their code
      should be informed by how much work it is for them. If they just

style-guide.md

@@ -75,6 +75,37 @@ prefer the url form, e.g.
 
 [goog-style-todo]: https://google.github.io/styleguide/cppguide.html#TODO_Comments
 
+### Deprecation
+
+Annotate the declarations of deprecated functions and classes with
+[ABSL_DEPRECATED][ABSL_DEPRECATED] to cause an error when they're used inside
+webrtc and a compiler warning when they're used by dependant projects. Like so:
+
+```
+ABSL_DEPRECATED("bugs.webrtc.org/12345")
+std::pony PonyPlz(const std::pony_spec& ps);
+```
+
+NOTE 1: The annotation goes on the declaration in the .h file, not the
+definition in the .cc file!
+
+NOTE 2: In order to have unit tests that use the deprecated function without
+getting errors, do something like this:
+
+```
+std::pony DEPRECATED_PonyPlz(const std::pony_spec& ps);
+ABSL_DEPRECATED("bugs.webrtc.org/12345")
+inline std::pony PonyPlz(const std::pony_spec& ps) {
+  return DEPRECATED_PonyPlz(ps);
+}
+```
+
+In other words, rename the existing function, and provide an inline wrapper
+using the original name that calls it. That way, callers who are willing to
+call it using the DEPRECATED_-prefixed name don't get the warning.
+
+[ABSL_DEPRECATED]: https://source.chromium.org/chromium/chromium/src/+/master:third_party/abseil-cpp/absl/base/attributes.h?q=ABSL_DEPRECATED
+
 ### ArrayView
 
 When passing an array of values to a function, use `rtc::ArrayView`