[PATCH] eng/coding-deprecating: Convert wiki page to Rest

[Marçal Comajoan Cara]

Converted https://devel.rtems.org/wiki/Developer/Coding/Deprecating
to Rest, and TBDs into comments.

I also corrected some errors that where present in the original wiki page and
were confirmed by Joel Sherrill.

This work was part of GCI 2018.
---
 eng/coding-deprecating.rst | 87 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 85 insertions(+), 2 deletions(-)

diff --git a/eng/coding-deprecating.rst b/eng/coding-deprecating.rst
index 4ca4c7c..03265ed 100644
--- a/eng/coding-deprecating.rst
+++ b/eng/coding-deprecating.rst
@@ -6,6 +6,89 @@
 Deprectating Interfaces
 ***********************
 
-TBD  - Convert the following to Rest and insert into this file
-TBD  - https://devel.rtems.org/wiki/Developer/Coding/Deprecating
+.. COMMENT: TBD  - Convert the following to Rest and insert into this file
+.. COMMENT: TBD  - https://devel.rtems.org/wiki/Developer/Coding/Deprecating
+
+This page documents the procedures for deprecating a public-facing interface
+in RTEMS.
+
+Use the deprecate attribute
+---------------------------
+
+Add the ``RTEMS_COMPILER_DEPRECATED_ATTRIBUTE``, which for gcc wraps the
+deprecated attribute, to functions, structures, and global symbols exported
+by the deprecated interface. Update the doxygen for each of these with the
+``@deprecated`` command, for example:
+
+.. code-bock:: c
+
+  /**
+   * @brief RTEMS Feature
+   *
+   * @deprecated Feature is deprecated and will be removed.
+   */
+
+Add a warning for configured features in confdefs.h
+---------------------------------------------------
+
+For features that are enabled or configured through confdefs.h, the feature
+should be disabled by default and a compile-time warning message should be
+printed, something along the lines of:
+
+.. code-block:: c
+
+  #warning "CONFIGURE_FEATURE_XXX\n\t\t\t**** Deprecated and will be removed. ****"
+
+Update documentation
+--------------------
+
+Find references to the deprecated feature in the user manuals and wiki,
+and make a note that the features are deprecated and may be removed.
+
+Update support code using deprecated feature
+--------------------------------------------
+
+If there is support code using the feature, you will need to modify that
+support code to not use that feature. If the code cannot be immediately
+modified, file a ticket on the issue and disable the deprecated warning.
+The code will need to be addressed before the feature can be removed.
+
+If the code in question is such that the feature's use can benignly be
+removed when the feature is removed, then simply disable the deprecated
+warning as shown below.
+
+It is possible that a test may need to be split into two or more tests, so
+the code that is exercising the deprecated feature can be easily removed when
+the feature is removed.
+
+Disable deprecated warnings
+---------------------------
+
+After adding the deprecated attribute, the files which implement the method(s),
+any tests for them, and any support code using that feature that will remain
+until the feature is removed will need the deprecate warning disabled. If it is
+for an entire file, then using this:
+
+.. code-block:: c
+
+  /*
+   * We know this is deprecated and don't want a warning on every BSP built. */
+  #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+
+If it is for a section of code, then this is the appropriate code to surround
+the section with:
+
+.. code-block:: c
+
+  /*
+   * We know this is deprecated and don't want a warning on every BSP built. */
+  #pragma GCC diagnostic push
+  #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+    /**** Code using deprecated feature ****/
+  #pragma GCC diagnostic pop
+
+Add a release note
+------------------
+
+Add the feature to a list of deprecated interfaces in the release notes.
 
-- 
2.17.1