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.

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

🕙 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.

📢 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?

WRT

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.

After team discussions, we’ve decided to extend the deprecation period to allow users a smoother transition to the new API. Deprecations will be announced on the public mailing list and GitHub, with periodic reminders to remaining users of the deprecated API. Once all respondents have migrated, we will schedule the final removal.