From 7013b3b5a468a2ae8e39c4ea04e7e8272aaae8d2 Mon Sep 17 00:00:00 2001
From: Danil Chapovalov <danilchap@webrtc.org>
Date: Mon, 22 Feb 2021 14:31:26 +0100
Subject: [PATCH] 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   |  2 +-
 style-guide.md | 31 +++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/PRESUBMIT.py b/PRESUBMIT.py
index 678e504cb0..614968362c 100755
--- a/PRESUBMIT.py
+++ b/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
diff --git a/style-guide.md b/style-guide.md
index 80c3302156..4a3143f39c 100644
--- a/style-guide.md
+++ b/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`