From 652ef4c328ab7ec0bc7aa71561a7f6b9c75ef6b7 Mon Sep 17 00:00:00 2001 From: xiota Date: Sat, 27 Nov 2021 18:07:26 -0800 Subject: [PATCH 1/3] Expand ABI/API explanation in HACKING --- HACKING | 18 +++++++++++++----- po/.intltool-merge-cache.lock | 0 2 files changed, 13 insertions(+), 5 deletions(-) create mode 100644 po/.intltool-merge-cache.lock diff --git a/HACKING b/HACKING index 8d105c11fd..270d40098e 100644 --- a/HACKING +++ b/HACKING @@ -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 @@ -137,7 +145,7 @@ in plugindata.h. This is usually not needed if you're just appending fields to structs. The GEANY_API_VERSION value should be incremented for any changes to the plugin API, including appending elements. -If you're in any doubt when making changes to plugin API code, just ask us. +If you're in doubt when making changes to plugin API code, just ask us. Plugin API/ABI design ^^^^^^^^^^^^^^^^^^^^^ diff --git a/po/.intltool-merge-cache.lock b/po/.intltool-merge-cache.lock new file mode 100644 index 0000000000..e69de29bb2 From e7554c86044fe8dfa9fd572273220d30dde336f0 Mon Sep 17 00:00:00 2001 From: xiota Date: Sat, 27 Nov 2021 19:02:29 -0800 Subject: [PATCH 2/3] remove po/.intltool-merge-cache.lock --- po/.intltool-merge-cache.lock | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 po/.intltool-merge-cache.lock diff --git a/po/.intltool-merge-cache.lock b/po/.intltool-merge-cache.lock deleted file mode 100644 index e69de29bb2..0000000000 From 8d267aaddc41b1525057331a3d7d8552b0b37692 Mon Sep 17 00:00:00 2001 From: xiota Date: Sun, 28 Nov 2021 22:33:46 -0800 Subject: [PATCH 3/3] Restore the word "any" --- HACKING | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HACKING b/HACKING index 270d40098e..45b4852ce9 100644 --- a/HACKING +++ b/HACKING @@ -145,7 +145,7 @@ in plugindata.h. This is usually not needed if you're just appending fields to structs. The GEANY_API_VERSION value should be incremented for any changes to the plugin API, including appending elements. -If you're in doubt when making changes to plugin API code, just ask us. +If you're in any doubt when making changes to plugin API code, just ask us. Plugin API/ABI design ^^^^^^^^^^^^^^^^^^^^^