From 0dae0464c7cef7a79f6c6376450ace00155eba18 Mon Sep 17 00:00:00 2001
From: Michael Tautschnig <tautschn@amazon.com>
Date: Sat, 23 Mar 2019 12:37:14 +0000
Subject: [PATCH] Coding standard: Deprecation rules

Thus far, we operated an informal deprecation policy. This codifies our
informal six-months rule.
---
 CODING_STANDARD.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md
index 6eed28c60b..1f0a32be76 100644
--- a/CODING_STANDARD.md
+++ b/CODING_STANDARD.md
@@ -101,6 +101,16 @@ Formatting is enforced using clang-format. For more information about this, see
 - Use comments to explain the non-obvious
 - Use #if 0 for commenting out source code
 - Use #ifdef DEBUG to guard debug code
+- When deprecating interfaces, use the `DEPRECATED` macro, preferably together
+  with `SINCE`. For example,
+  ```
+  DEPRECATED(SINCE(2019, 1, 31, "use other_method() instead"))
+  void deprecated_method();
+  ```
+  marks `deprecated_method` as deprecated as of 2019-01-31. Any deprecated
+  functionality should remain in place for at least six months from the date of
+  deprecation. Before deprecating code, all in-tree uses should be replaced or
+  marked as deprecated.
 
 # Naming
 - Identifiers should make clear the purpose of the thing they are naming.