Deprecation process proposal #200
Description
How would you describe the topic that you would love to see in the documentation?
There will sometimes need to be changes to the interface that break compatibility with existing clients. During early development, it can be understood that such changes occur early and often.
However, as the project matures and has stable releases, those changes should be communicated early to allow for the developers of those clients to make the necessary changes to take advantage of new versions of EVerest code without risking downtime or being unable to take advantage of improvements due to incompatibilities introduced in a new release.
Such changes to existing interfaces/APIs should be phased in through a defined and well-understood deprecation process.
On which page or to which section does this belong?
There will need to be two separate pieces of documentation.
One is for developers of EVerest to know how to mark code as deprecated and the process for eventually sunsetting the code, and it probably makes sense to add to the tutorials here: https://everest.github.io/nightly/tutorials/index.html
The other is for clients of EVerest to know what to look for when integrating the libraries. Perhaps under the troubleshooting section of https://github.com/EVerest/everest-core#readme
Additional context
Deprecation Process
Proposed process for C++ code:
When public-facing code (functions, data members, etc) is outdated, obsolete, or being replaced with a different implementation is preferred, it should be marked as deprecated for one major release cycle, after which the code can be removed in the next major release. NOTE: There probably does not need to be a formal decision made by the community, as the pull request process should drive the conversation about whether or not code should be deprecated.
The [[deprecated]] attribute has been available since C++14, and examples of how to use it are available at: https://en.cppreference.com/w/cpp/language/attributes/deprecated
When using the attribute, the string-literal should be supplied such that it explains what should be used instead, if a replacement or new interface is available, or at least an explanation for why the code should not be used going forward if there is not an appropriate replacement.
If the deprecated code is being replaced with code that is different in a non-trivial way, it may help to create a migration document to explain how to migrate code from the deprecated code to the replacement code, and the [[deprecated]] attribute's string-literal should point to that documentation.
When a new release is being prepared, code marked as deprecated in the previous release should be tracked so it can be removed before the new release.
NOTE: Perhaps there should be a second stage after deprecated to make it easier to manage deprecation AND allow users yet another chance to update client code. So one release cycle with [[deprecated]] followed by one release cycle with something to indicate that it is now sunset (C++17 allows arbitrary attributes without error), then at the next release cycle the sunset code is removed and all deprecated code is marked sunset.
Any release notes should list the current list of deprecated functionality and data members.
Deprecation notification
Aside from the release notes, CMake by default will configure the build to issue warnings about deprecated functionality https://cmake.org/cmake/help/latest/variable/CMAKE_WARN_DEPRECATED.html
If the API change is complex enough, perhaps the [[deprecated]] attribute can point to a migration document to explain how to update client code so that it uses the new code rather than the deprecated code.