Merge pull request #379 from abique/1.2.0/ext-id-cleanup

1.2.0 - Cleanup stabilized extension ID
free-audio · Jan 15, 2024 · 4e7622d · 4e7622d
2 parents 12ca18f + 5c52b38
commit 4e7622d
Show file tree

Hide file tree

Showing 12 changed files with 69 additions and 32 deletions.
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -1,5 +1,9 @@
 # Changes in 1.2.0
 
+## New conventions
+
+* [extension-id](conventions/extension-id.md): introduce some rules about extension ID naming.
+
 ## Stabilize extensions
 
 * `CLAP_EXT_AMBISONIC`
@@ -13,8 +17,17 @@
 * `CLAP_EXT_SURROUND`
 * `CLAP_EXT_TRACK_INFO`
 
-Note: we kept the last draft extension ID in order to not break plugins already using it.
-Note: remaining draft extension ID as been updated to follow the new convention.
+### Notes regarding extension ID change after draft stabilization
+
+We changed the extension ID in the process of stabilization which leads to a **break**.
+
+To mitigate this transition, we've provided compatibility extension IDs which can be used to match and use the latest draft extensions as they are 100% compatible.
+
+For example, `CLAP_EXT_CONTEXT_MENU` for the stable ID and `CLAP_EXT_CONTEXT_MENU_COMPAT` for the draft ID.
+
+As you can see in [extension-id](conventions/extension-id.md), we introduced some rules, so this kind of break won't happen again.
+
+We may decide to remove the `*_COMPAT` IDs in the future once their usage becomes antiquated.
 
 ## Removed draft extensions
 
@@ -38,10 +51,6 @@ Note: we kept the last draft factory ID in order to not break plugins already us
 * [params.h](include/clap/ext/params.h): Fix incorrect function name reference
 * [latency.h](include/clap/ext/latency.h): Require the plugin to be activated to get the latency and clarify that the latency can only be fetched when the plugin is activated
 
-## Conventions
-
-* [extension-id](conventions/extension-id.md): introduce some rules about extension ID naming.
-
 ## Plugin Template
 
 * [plugin-template.c](src/plugin-template.c): implement thread-safe plugin entry init counter

diff --git a/conventions/extension-id.md b/conventions/extension-id.md
@@ -27,6 +27,6 @@ Everything about the extension id symmetrically applies to factory id.
 
 ## History
 
-Before this document was written, existing extensions didn't honor these rules.
-Some stable extensions include the string `draft` in their ID.
-We decided to keep those in order to maintain binary compatibility.
+Before version 1.2.0 when this document was written, existing extensions didn't honor these rules.
+We wanted to stabilize some draft extensions without breaking compatibility, yet their extension IDs contained the string `draft`.
+While these strings weren't user-facing, we still wanted to remove them, so we updated the extension IDs according to this document and introduced IDs with `_COMPAT` suffixes to provide backward compatibility with the draft versions.
diff --git a/include/clap/ext/audio-ports-activation.h b/include/clap/ext/audio-ports-activation.h
@@ -25,9 +25,12 @@
 /// Audio ports state is invalidated by clap_plugin_audio_ports_config.select() and
 /// clap_host_audio_ports.rescan(CLAP_AUDIO_PORTS_RESCAN_LIST).
 
-// This extension ID contains `draft', yet it is stable.
-// See conventions/extension-id.md for more info.
 static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_ACTIVATION[] =
+   "clap.audio-ports-activation/2";
+
+// The latest draft is 100% compatible.
+// This compat ID may be removed in 2026.
+static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_ACTIVATION_COMPAT[] =
    "clap.audio-ports-activation/draft-2";
 
 #ifdef __cplusplus

diff --git a/include/clap/ext/audio-ports-config.h b/include/clap/ext/audio-ports-config.h
@@ -27,9 +27,12 @@
 
 static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_CONFIG[] = "clap.audio-ports-config";
 
-// This extension ID contains `draft', yet it is stable.
-// See conventions/extension-id.md for more info.
 static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_CONFIG_INFO[] =
+   "clap.audio-ports-config-info/1";
+
+// The latest draft is 100% compatible.
+// This compat ID may be removed in 2026.
+static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_CONFIG_INFO_COMPAT[] =
    "clap.audio-ports-config-info/draft-0";
 
 #ifdef __cplusplus

diff --git a/include/clap/ext/configurable-audio-ports.h b/include/clap/ext/configurable-audio-ports.h
@@ -9,9 +9,12 @@ extern "C" {
 // This extension lets the host configure the plugin's input and output audio ports.
 // This is a "push" approach to audio ports configuration.
 
-// This extension ID contains `draft', yet it is stable.
-// See conventions/extension-id.md for more info.
 static CLAP_CONSTEXPR const char CLAP_EXT_CONFIGURABLE_AUDIO_PORTS[] =
+   "clap.configurable-audio-ports/1";
+
+// The latest draft is 100% compatible.
+// This compat ID may be removed in 2026.
+static CLAP_CONSTEXPR const char CLAP_EXT_CONFIGURABLE_AUDIO_PORTS_COMPAT[] =
    "clap.configurable-audio-ports.draft1";
 
 typedef struct clap_audio_port_configuration_request {

diff --git a/include/clap/ext/context-menu.h b/include/clap/ext/context-menu.h
@@ -5,9 +5,11 @@
 // This extension lets the host and plugin exchange menu items and let the plugin ask the host to
 // show its context menu.
 
-// This extension ID contains `draft', yet it is stable.
-// See conventions/extension-id.md for more info.
-static CLAP_CONSTEXPR const char CLAP_EXT_CONTEXT_MENU[] = "clap.context-menu.draft/0";
+static CLAP_CONSTEXPR const char CLAP_EXT_CONTEXT_MENU[] = "clap.context-menu/1";
+
+// The latest draft is 100% compatible.
+// This compat ID may be removed in 2026.
+static CLAP_CONSTEXPR const char CLAP_EXT_CONTEXT_MENU_COMPAT[] = "clap.context-menu.draft/0";
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/clap/ext/preset-load.h b/include/clap/ext/preset-load.h
@@ -2,9 +2,11 @@
 
 #include "../plugin.h"
 
-// This extension ID contains `draft', yet it is stable.
-// See conventions/extension-id.md for more info.
-static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load.draft/2";
+static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load/2";
+
+// The latest draft is 100% compatible.
+// This compat ID may be removed in 2026.
+static const char CLAP_EXT_PRESET_LOAD_COMPAT[] = "clap.preset-load.draft/2";
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/clap/ext/remote-controls.h b/include/clap/ext/remote-controls.h
@@ -31,9 +31,11 @@
 // Pressing that button once gets you to the first page of the section.
 // Press it again to cycle through the section's pages.
 
-// This extension ID contains `draft', yet it is stable.
-// See conventions/extension-id.md for more info.
-static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS[] = "clap.remote-controls.draft/2";
+static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS[] = "clap.remote-controls/2";
+
+// The latest draft is 100% compatible
+// This compat ID may be removed in 2026.
+static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS_COMPAT[] = "clap.remote-controls.draft/2";
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/clap/ext/state-context.h b/include/clap/ext/state-context.h
@@ -32,7 +32,11 @@
 extern "C" {
 #endif
 
-static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context/2";
+static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context/1";
+
+// The latest draft is 100% compatible.
+// This compat ID may be removed in 2026.
+static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT_COMPAT[] = "clap.state-context.draft/1";
 
 enum clap_plugin_state_context_type {
    // suitable for storing and loading a state as a preset

diff --git a/include/clap/ext/surround.h b/include/clap/ext/surround.h
@@ -24,9 +24,11 @@
 // 3. host calls clap_plugin_surround->get_channel_map()
 // 4. host activates the plugin and can start processing audio
 
-// This extension ID contains `draft', yet it is stable.
-// See conventions/extension-id.md for more info.
-static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND[] = "clap.surround.draft/4";
+static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND[] = "clap.surround/4";
+
+// The latest draft is 100% compatible.
+// This compat ID may be removed in 2026.
+static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND_COMPAT[] = "clap.surround.draft/4";
 
 static CLAP_CONSTEXPR const char CLAP_PORT_SURROUND[] = "surround";
 

diff --git a/include/clap/ext/track-info.h b/include/clap/ext/track-info.h
@@ -7,10 +7,12 @@
 // This extension let the plugin query info about the track it's in.
 // It is useful when the plugin is created, to initialize some parameters (mix, dry, wet)
 // and pick a suitable configuration regarding audio port type and channel count.
-//
-// This extension ID contains `draft', yet it is stable.
-// See conventions/extension-id.md for more info.
-static CLAP_CONSTEXPR const char CLAP_EXT_TRACK_INFO[] = "clap.track-info.draft/1";
+
+static CLAP_CONSTEXPR const char CLAP_EXT_TRACK_INFO[] = "clap.track-info/1";
+
+// The latest draft is 100% compatible.
+// This compat ID may be removed in 2026.
+static CLAP_CONSTEXPR const char CLAP_EXT_TRACK_INFO_COMPAT[] = "clap.track-info.draft/1";
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h
@@ -49,6 +49,11 @@
 // Use it to retrieve const clap_preset_discovery_factory_t* from
 // clap_plugin_entry.get_factory()
 static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID[] =
+   "clap.preset-discovery-factory/2";
+
+// The latest draft is 100% compatible.
+// This compat ID may be removed in 2026.
+static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID_COMPAT[] =
    "clap.preset-discovery-factory/draft-2";
 
 #ifdef __cplusplus