From 3a3faaa253a59a053ab372bceeb206885995a89c Mon Sep 17 00:00:00 2001 From: Nick Wellnhofer Date: Tue, 30 Sep 2025 18:05:32 +0200 Subject: [PATCH] Document process to remove API functions in MAINTAINERS.md --- MAINTAINERS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/MAINTAINERS.md b/MAINTAINERS.md index fe214f163..081a85b1e 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -79,6 +79,24 @@ Create or update a GitLab release on Announce the release on https://discourse.gnome.org under topics 'libxml2' and 'announcements'. +## Removing public API functions + +General process to remove public API functions (or variables): + +- Make sure that there's a reasonable alternative. +- Mark the function as deprecated in the documentation and mention + alternatives. +- Mark the function as XML_DEPRECATED in the header files. +- For whole modules: disable the module by default and only enable + it in "legacy mode". +- Remove the function body and make the function return an error code + or a no-op. Make sure that the symbol is kept and exported. This + should only be done after allowing users enough time to adjust. +- At the next ABI bump, remove the symbol completely. + +You can wait for the next feature release between some of the steps to +make the process more gradual. + ## Breaking the ABI Unfortunately, libxml2 exposes many internal structs which makes some