[geany/geany] d8f2f1: Expand ABI/API explanation in HACKING (#3027)
git-noreply at xxxxx
Mon Nov 29 08:35:02 UTC 2021
Author: xiota <xiota at users.noreply.github.com>
Committer: GitHub <noreply at github.com>
Date: Mon, 29 Nov 2021 08:35:02 UTC
Expand ABI/API explanation in HACKING (#3027)
* Expand ABI/API explanation in HACKING
16 lines changed, 12 insertions(+), 4 deletions(-)
@@ -126,10 +126,18 @@ the existing elements stay in place - this will keep the ABI stable.
Keeping the plugin ABI stable
-Before the 1.0 release series, the ABI can change when necessary, and
-even the API can change. An ABI change just means that all plugins will
-not load and they must be rebuilt. An API change means that some plugins
-might not build correctly.
+In general the ABI changes as little as we can manage. The ABI number
+must match exactly between Geany and plugins, so an ABI change breaks
+all plugins until they are re-compiled. But sometimes it is absolutely
+necessary. Removing a feature or significantly changing the semantics
+of an existing feature require an ABI change since existing plugins may
+no longer work with the modified version of Geany.
+The API identifying number is increased whenever anything is added to
+the API so plugins can test if the feature is available. The API number
+required by a plugin needs only to be lower than the API Geany provides,
+so an increase in API number without a change in ABI will not stop
+plugins that need a lower number from working.
If you're reordering or changing existing elements of structs that are
used as part of the plugin API, you must increment GEANY_ABI_VERSION
This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).
More information about the Commits