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.