[geany/geany] d8f2f1: Expand ABI/API explanation in HACKING (#3027)

[xiota]

Branch:      refs/heads/master
Author:      xiota <xiota at users.noreply.github.com>
Committer:   GitHub <noreply at github.com>
Date:        Mon, 29 Nov 2021 08:35:02 UTC
Commit:      d8f2f14a16fe57fb1a98e767a2263846a0135431
             https://github.com/geany/geany/commit/d8f2f14a16fe57fb1a98e767a2263846a0135431

Log Message:
-----------
Expand ABI/API explanation in HACKING (#3027)

* Expand ABI/API explanation in HACKING


Modified Paths:
--------------
    HACKING

Modified: 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).