-
Notifications
You must be signed in to change notification settings - Fork 0
Deprecation policy draft
The conversation in RIOT #10108 expressed the need for a deprecation policy. This document is a draft.
As RIOT matures, it's fair for a user to ask about the stability of APIs. At the same time we need to innovate as the need arises. A deprecation policy provides assurance to the user on how we end-of-life an API so they can decide whether to upgrade RIOT to a new release.
- Compare to other projects. What do they do?
- Is deprecation married to a versioning policy for a particular API? Or is versioning a separate issue?
Presently some API functions are marked with an @deprecated tag in the API documentation, for example gcoap_req_send(). In addition, these deprecated functions are shown together on the Deprecated List page in the documentation. This approach looks reasonable to me.
However, the reader does not know when the function actually will be removed from RIOT. Assuming we add this information, as discussed below in the Lifetime section, we also should specify the last release in which the function will appear.
- For how long should an artifact remain deprecated before removal?
- Can we be flexible? Might the deprecation period depend on the effort to remove or the extent of use of the artifact?
- What is the process for actually removing an artifact? Is this part of the release mechanism for those artifacts slated for removal with a particular release?
- How should we publish this policy? Put a file in the root directory? Add to a prominent place in the project documentation? Place it somewhere on the wiki?