Document deprecation for API functions

[inknos]

Currently, DNF5 does not have a clear policy on how to deprecate public API functions. We should document the process and be clear on how to intervene in such instances. Take this commit, which generated the discussion, as an example.

• [ ] Firstly, considering that DNF5's API is stable, we should remind in the documentation the deprecation steps that we would follow. As an example, we could follow Fedora release steps, the deprecation process should be documented e.g.,
  1. Announcing deprecation during one fedora release
  2. Removing the function on the next fedora, or something like that.
• [ ] document how deprecation is handled as warnings in the codebase. There are three steps that should be targeted:
  • [ ] build time warning: how should warnings be handled and how noisy should the deprecation warnings be at build time
  • [ ] runtime warning: how should warnings be printed when using the C++ API or the Python API at runtime
  • [ ] documentation warning: currently, warnings are just a word in the docs, they are not visible enough. See here. This should be automated and generally improved to avoid confusion.

[jan-kolarik]

The current approach to handling deprecated methods has been reported as insufficient by our API clients. Before implementing any changes, we should review existing standards to increase the likelihood of detecting issues using the existing CI checkers deployed by our dependents.

[jan-kolarik]

I think it’s time to decide on an approach here. Following @inknos’s proposal, here are my suggestions:

:clock10: Deprecation timeline documentation

Align with Fedora release cycles: mark objects or methods as deprecated at the start of a release and remove them in the subsequent release. Document this approach in our documentation.

:loudspeaker: Deprecation signaling implementation

Documentation visibility

Mark deprecated elements in docstrings with @deprecated and apply a custom style to make this tag more visible in upstream docs.

Optionally, create a dedicated deprecation list section.

Build-time warnings for C++ users

Use [[deprecated]], which has been standard since C++14.

Runtime user notifications

Define e.g. a LIBDNF_DEPRECATED macro wrapper to log a warning to stderr whenever a deprecated method is called. Question: Should this also apply to C++ API users, even though they already receive a build-time warning?