= Deprecating Public Application Programming Interfaces =

[[TOC(Developer/Coding/Deprecating, depth=2)]]

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 [https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html 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,
{{{#!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
{{{#!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 (doc) and wiki, and make a note that the features are deprecated and may be removed.

== Add a release note ==
Add the feature to a list of deprecated interfaces in the release notes.