Introduce deprecation policy to developer guide. (#10252)

This PR resolves #10159.

Authors:
  - Vyas Ramasubramani (https://github.com/vyasr)

Approvers:
  - Vukasin Milovanovic (https://github.com/vuule)
  - Bradley Dice (https://github.com/bdice)
  - Jake Hemstad (https://github.com/jrhemstad)
  - Nghia Truong (https://github.com/ttnghia)
  - Mark Harris (https://github.com/harrism)

URL: #10252

cpp/docs/DEVELOPER_GUIDE.md

@@ -745,6 +745,30 @@ void isolated_helper_function(...);
 
 [**Anonymous namespaces should *never* be used in a header file.**](https://wiki.sei.cmu.edu/confluence/display/cplusplus/DCL59-CPP.+Do+not+define+an+unnamed+namespace+in+a+header+file)
 
+# Deprecating and Removing Code
+
+libcudf is constantly evolving to improve performance and better meet our users' needs. As a
+result, we occasionally need to break or entirely remove APIs to respond to new and improved
+understanding of the functionality we provide. Remaining free to do this is essential to making
+libcudf an agile library that can rapidly accommodate our users needs. As a result, we do not
+always provide a warning or any lead time prior to releasing breaking changes. On a best effort
+basis, the libcudf team will notify users of changes that we expect to have significant or
+widespread effects.
+
+Where possible, indicate pending API removals using the
+[deprecated](https://en.cppreference.com/w/cpp/language/attributes/deprecated) attribute and
+document them using Doxygen's
+[deprecated](https://www.doxygen.nl/manual/commands.html#cmddeprecated) command prior to removal.
+When a replacement API is available for a deprecated API, mention the replacement in both the
+deprecation message and the deprecation documentation. Pull requests that introduce deprecations
+should be labeled "deprecation" to facilitate discovery and removal in the subsequent release.
+
+Advertise breaking changes by labeling any pull request that breaks or removes an existing API with
+the "breaking" tag. This ensures that the "Breaking" section of the release notes includes a
+description of what has broken from the past release. Label pull requests that contain deprecations
+with the "non-breaking" tag.
+
+
 # Error Handling
 
 libcudf follows conventions (and provides utilities) enforcing compile-time and run-time

cpp/docs/DOCUMENTATION.md

@@ -369,6 +369,20 @@ Although using 3 backtick marks `` ``` `` for example blocks will work too, they
 Do not use the `@example` tag in the comments for a declaration, or doxygen will interpret the entire source file as example source code.
 The source file is then published under a separate _Examples_ page in the output.
 
+### Deprecations
+
+Add a single [@deprecated](https://www.doxygen.nl/manual/commands.html#cmddeprecated) comment line
+to comment blocks for APIs that will be removed in future releases. Mention alternative /
+replacement APIs in the deprecation comment.
+
+```c++
+/**
+ * ...
+ *
+ * @deprecated This function is deprecated. Use another new function instead.
+ */
+```
+
 ## Namespaces
 
 Doxygen output includes a _Namespaces_ page that shows all the namespaces declared with comment blocks in the processed files.