---

name: webrtc/avoid-raw-deprecated-on-public-api description: ‘When deprecating public C++ APIs or modernizing signatures in headers, avoid raw [[deprecated]] and #pragma suppressions; use TODO comments or ABSL_DEPRECATE_AND_INLINE delegating wrappers’ rubric: readability severity: blocking

Rule. When deprecating or replacing public API constructors, methods, functions, enum values, type aliases, or header transition shims in C++ headers, do not annotate legacy declarations with raw [[deprecated]] or ABSL_DEPRECATED while downstream consumers (such as Chromium) still invoke or reference them under -Werror, and do not add #pragma clang diagnostic ignored "-Wdeprecated-declarations" suppression blocks around header delegating fallbacks.

Instead:

1. Retain an unannotated delegating shim, virtual fallback, or enum alias accompanied by a tracking bug comment (e.g. // TODO(bugs.webrtc.org/12345): Deprecated in favor of ...).
2. Alternatively, use ABSL_DEPRECATE_AND_INLINE() for inline functions, signature modernizations (such as migrating raw pointer and length pairs to ArrayView or span), and type aliases (using Foo ABSL_DEPRECATE_AND_INLINE() = Bar;). When doing so, include "absl/base/macros.h" and add //third_party/abseil-cpp/absl/base:core_headers to BUILD.gn deps.
3. Migrate downstream callers first, then remove legacy symbols in a dedicated follow-up CL.

Why. Downstream consumers such as Chromium compile against WebRTC public headers with compiler warnings treated as errors (-Werror). Marking active public symbols, methods, enum values, type aliases, or header transition shims with raw [[deprecated]] or ABSL_DEPRECATED triggers immediate compilation failures (-Wdeprecated-declarations) upon dependency rolls before downstream callers migrate, or introduces unsightly compiler pragma suppression blocks into public headers. Retaining unannotated shims with tracking TODOs or using ABSL_DEPRECATE_AND_INLINE() (which is patched in Chromium and WebRTC not to emit [[deprecated]]) enables clean, safe, multi-step migrations without breaking downstream builds.

Examples

Bad:

// Bad: Raw [[deprecated]] breaks downstream -Werror builds:
[[deprecated("Use Timestamp overload instead")]]
RTCStats(std::string id, int64_t timestamp_us);

// Bad: Adding deprecation attributes and #pragma suppressions to header shims:
ABSL_DEPRECATED("Use SendPacketWithStatus instead")
virtual void SendPacket(rtc::ArrayView<const uint8_t> data) {}

virtual SendPacketStatus SendPacketWithStatus(rtc::ArrayView<const uint8_t> data) {
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wdeprecated-declarations"
  SendPacket(data);
#pragma clang diagnostic pop
  return SendPacketStatus::kSuccess;
}

// Bad: Modernizing signature without preserving legacy delegating wrapper:
std::vector<uint8_t> ParseRbsp(rtc::ArrayView<const uint8_t> data);

Good:

// Good: Retain unannotated delegating shim with tracking TODO:
// TODO(webrtc:12345): Remove once downstream consumers migrate.
RTCStats(std::string id, int64_t timestamp_us)
    : RTCStats(std::move(id), Timestamp::Micros(timestamp_us)) {}

// Good: Document deprecation in TODO comment without compiler attributes or #pragma:
// TODO(bugs.webrtc.org/12345): Deprecated in favor of SendPacketWithStatus.
virtual void SendPacket(rtc::ArrayView<const uint8_t> data) {}

virtual SendPacketStatus SendPacketWithStatus(rtc::ArrayView<const uint8_t> data) {
  SendPacket(data);
  return SendPacketStatus::kSuccess;
}

// Good: Use ABSL_DEPRECATE_AND_INLINE wrapper forwarding to modernized signature:
#include "absl/base/macros.h"
std::vector<uint8_t> ParseRbsp(rtc::ArrayView<const uint8_t> data);

ABSL_DEPRECATE_AND_INLINE()
inline std::vector<uint8_t> ParseRbsp(const uint8_t* data, size_t length) {
  return ParseRbsp(rtc::MakeArrayView(data, length));
}