From 3aa3165fe9c23b71cf31b914450a5cd1a2fd4805 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 12 Jan 2024 10:19:00 +0100 Subject: [PATCH 1/8] Remove draft from the extension id --- conventions/extension-id.md | 5 +++-- include/clap/ext/audio-ports-activation.h | 7 +++++-- include/clap/ext/audio-ports-config.h | 7 +++++-- include/clap/ext/configurable-audio-ports.h | 7 +++++-- include/clap/ext/context-menu.h | 8 +++++--- include/clap/ext/preset-load.h | 8 +++++--- include/clap/ext/remote-controls.h | 7 ++++--- include/clap/ext/state-context.h | 6 +++++- include/clap/ext/surround.h | 8 +++++--- include/clap/ext/track-info.h | 10 ++++++---- include/clap/factory/preset-discovery.h | 4 ++++ 11 files changed, 52 insertions(+), 25 deletions(-) diff --git a/conventions/extension-id.md b/conventions/extension-id.md index c07b22a0..2ec9399d 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -28,5 +28,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. \ No newline at end of file +We wanted to stabilize some extension without breaking the compatibility, yet the extension ID contained the string `draft`. +While this isn't user facing, we wanted to get rid of it, so we updated the extension ID according to this document and +introduced a `XXX_COMPAT` ID to provide backward compatibility with the draft version. diff --git a/include/clap/ext/audio-ports-activation.h b/include/clap/ext/audio-ports-activation.h index a138a63d..f63085c5 100644 --- 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 index 0f56f1dc..2ab86573 100644 --- 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 index 56a462bd..86688e71 100644 --- 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 index 1ef40023..293f59a8 100644 --- 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 index 8b76a0a7..3dbf7375 100644 --- 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 index ad045faa..2d4a7d0b 100644 --- a/include/clap/ext/remote-controls.h +++ b/include/clap/ext/remote-controls.h @@ -31,9 +31,10 @@ // 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 +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 index 20248b37..d4c05930 100644 --- 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 index ce85886c..7e57c051 100644 --- 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 index 7114a6be..3e1a5559 100644 --- 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 index 752b3a4b..90be92ef 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -49,6 +49,10 @@ // 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"; + +// The latest draft is 100% compatible +static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID_COMPAT[] = "clap.preset-discovery-factory/draft-2"; #ifdef __cplusplus From 42a9ee2b329e8ea3eef6569f00295ad20a9600d4 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 12 Jan 2024 10:22:30 +0100 Subject: [PATCH 2/8] Update changelog --- ChangeLog.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 7787b128..0b61686e 100644 --- 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 provide a compatibily extension ID which can be used to match and use the draft extension 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 introduce some rules, so this kind of breaks won't happen again. + +We may decide to remove `CLAP_EXT_CONTEXT_MENU_COMPAT` in the future once their usage becomes anecdotic. ## 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 From abcd29bdbe6b25243abc9b1091dce72dce9dd832 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 12 Jan 2024 10:23:05 +0100 Subject: [PATCH 3/8] Update preset-discovery extension id to follow the convention. --- include/clap/factory/preset-discovery.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h index 90be92ef..2f788c7b 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -49,7 +49,7 @@ // 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"; + "clap.preset-discovery-factory/2"; // The latest draft is 100% compatible static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID_COMPAT[] = From 522e69d50fbd0bec8268ef997d8da82f9f5fa9e6 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 12 Jan 2024 10:25:41 +0100 Subject: [PATCH 4/8] Missing deprecation notice --- include/clap/factory/preset-discovery.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h index 2f788c7b..f9c8e434 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -51,7 +51,8 @@ static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID[] = "clap.preset-discovery-factory/2"; -// The latest draft is 100% compatible +// 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"; From 17e1b524c2e3b812b33df943227ddccd3029239f Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 13 Jan 2024 10:34:30 +0100 Subject: [PATCH 5/8] Update ChangeLog.md Co-authored-by: Dalton Messmer --- ChangeLog.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 0b61686e..a3342bd5 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -21,13 +21,13 @@ We changed the extension ID in the process of stabilization which leads to a **break**. -To mitigate this transition, we provide a compatibily extension ID which can be used to match and use the draft extension as they are 100% compatible. +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 introduce some rules, so this kind of breaks won't happen again. +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 `CLAP_EXT_CONTEXT_MENU_COMPAT` in the future once their usage becomes anecdotic. +We may decide to remove the `*_COMPAT` IDs in the future once their usage becomes antiquated. ## Removed draft extensions From 11ef4a15b43fbfb030a1660571c8ee32e0aa586a Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 13 Jan 2024 10:35:49 +0100 Subject: [PATCH 6/8] Update conventions/extension-id.md Co-authored-by: Dalton Messmer --- conventions/extension-id.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/conventions/extension-id.md b/conventions/extension-id.md index 2ec9399d..ab397895 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -28,6 +28,5 @@ Everything about the extension id symmetrically applies to factory id. ## History Before this document was written, existing extensions didn't honor these rules. -We wanted to stabilize some extension without breaking the compatibility, yet the extension ID contained the string `draft`. -While this isn't user facing, we wanted to get rid of it, so we updated the extension ID according to this document and -introduced a `XXX_COMPAT` ID to provide backward compatibility with the draft version. +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. From 5373d31fceb6218daf63cdccc9d1c18941212da0 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 13 Jan 2024 10:36:38 +0100 Subject: [PATCH 7/8] Update include/clap/ext/remote-controls.h Co-authored-by: Dalton Messmer --- include/clap/ext/remote-controls.h | 1 + 1 file changed, 1 insertion(+) diff --git a/include/clap/ext/remote-controls.h b/include/clap/ext/remote-controls.h index 2d4a7d0b..d7bf4fc5 100644 --- a/include/clap/ext/remote-controls.h +++ b/include/clap/ext/remote-controls.h @@ -34,6 +34,7 @@ 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 From 5c52b38d7e69256ba1d7a654be0ed043107a692a Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 13 Jan 2024 10:40:57 +0100 Subject: [PATCH 8/8] Update extension-id.md Apply changes suggested by @messmerd --- conventions/extension-id.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conventions/extension-id.md b/conventions/extension-id.md index ab397895..4b0b5c11 100644 --- 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. +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.