diff --git a/cpp/docs/DEVELOPER_GUIDE.md b/cpp/docs/DEVELOPER_GUIDE.md index 1599c81cbe5..165edd443f6 100644 --- a/cpp/docs/DEVELOPER_GUIDE.md +++ b/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 diff --git a/cpp/docs/DOCUMENTATION.md b/cpp/docs/DOCUMENTATION.md index 2382a0eb022..ebb52836577 100644 --- a/cpp/docs/DOCUMENTATION.md +++ b/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.