Provide the mechanism for the API deprecation

XVilka commented 3 years ago

While we are before the 1.x versions, it's relatively safe to change the API as we wish. On the other hand, after releasing the 1.x version it will be no longer the case. Thus I propose the way to deprecate the API:

Define the deprecation window. Usually it's 1 after 1 major release: 1st one will be deprecating the API, 2nd will remove the deprecated API
Separate those APIs as the wrappers of the newer API whenever possible
Mark them somehow in the function signature - RZ_DEPRECATED macro or something similar
Add a preprocessor/compiler warning, e.g. #warning that will make the developers who use this API to notice
If there will be non-C bindings provide the similar mechanisms to warn the developer too

ret2libc commented 3 years ago

The API will be the commands so this does not apply. However, we can add a deprecated bool to each command descriptor to mark it as deprecated.

We could also have an experimental bool to clearly show users commands that were recently added and might not be completely stable yet

stale[bot] commented 2 years ago

This issue has been automatically marked as stale because it has not had recent activity. Considering a lot has probably changed since its creation, we kindly ask you to check again if the issue you reported is still relevant in the current version of rizin. If it is, update this issue with a comment, otherwise it will be automatically closed if no further activity occurs. Thank you for your contributions.

stale[bot] commented 2 years ago

This issue has been automatically marked as stale because it has not had recent activity. Considering a lot has probably changed since its creation, we kindly ask you to check again if the issue you reported is still relevant in the current version of rizin. If it is, update this issue with a comment, otherwise it will be automatically closed if no further activity occurs. Thank you for your contributions.

stale[bot] commented 2 years ago

This issue has been automatically closed because marked as stale and it has not been updated since then. If the issue is still relevant, feel free to re-open it or open a new one.

XVilka commented 2 years ago

@wingdeans it might be of interest for you as well.

rizinorg / ideas

Provide the mechanism for the API deprecation #32