diff --git a/libgimp/gimpvectorloadprocedure.c b/libgimp/gimpvectorloadprocedure.c
index 2cbfab60b4..87c9c6a4ba 100644
--- a/libgimp/gimpvectorloadprocedure.c
+++ b/libgimp/gimpvectorloadprocedure.c
@@ -24,6 +24,7 @@
 
 #include "gimp.h"
 
+#include "libgimpbase/gimpversion-private.h"
 #include "libgimpbase/gimpwire.h" /* FIXME kill this include */
 
 #include "gimpvectorloadprocedure.h"
@@ -132,9 +133,7 @@ gimp_vector_load_procedure_constructed (GObject *object)
                                        FALSE,
                                        G_PARAM_READWRITE);
 
-#if GIMP_CHECK_VERSION(3, 99, 0)
-#warning Make per-coordinate x/y pixel density. Simplify plug-ins/common/file-svg.c code when not keeping ratio.
-#endif
+  GIMP_WARNING_API_BREAK("Make per-coordinate x/y pixel density. Simplify plug-ins/common/file-svg.c code when not keeping ratio.")
 
   /* Note: the "pixel-density" is saved in pixels per inch. "physical-unit"
    * property is only there for display.
diff --git a/libgimpbase/gimpmetadata.c b/libgimpbase/gimpmetadata.c
index ca31fc5e3e..d466512853 100644
--- a/libgimpbase/gimpmetadata.c
+++ b/libgimpbase/gimpmetadata.c
@@ -28,6 +28,7 @@
 #include <gegl.h>
 #include <gio/gio.h>
 
+#include "libgimpbase/gimpversion-private.h"
 #include "libgimpmath/gimpmath.h"
 
 #include "gimpbasetypes.h"
@@ -41,9 +42,7 @@
 #include "libgimp/libgimp-intl.h"
 
 
-#if GIMP_CHECK_VERSION(3, 99, 0)
-#warning libgimpbase/gimpmetadata.h: rename GIMP_METADATA_SAVE_UPDATE as GIMP_METADATA_UPDATE?
-#endif
+GIMP_WARNING_API_BREAK("libgimpbase/gimpmetadata.h: rename GIMP_METADATA_SAVE_UPDATE as GIMP_METADATA_UPDATE?")
 
 /**
  * SECTION: gimpmetadata
diff --git a/libgimpbase/gimpversion-private.h b/libgimpbase/gimpversion-private.h
new file mode 100644
index 0000000000..3482281f19
--- /dev/null
+++ b/libgimpbase/gimpversion-private.h
@@ -0,0 +1,66 @@
+/* LIBGIMP - The GIMP Library
+ * Copyright (C) 1995-1997 Peter Mattis and Spencer Kimball
+ *
+ * gimpversion-private.h
+ * Copyright (C) 2025 Jehan
+ *
+ * This library is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library.  If not, see
+ * <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef __GIMP_VERSION_PRIVATE_H__
+#define __GIMP_VERSION_PRIVATE_H__
+
+#include <libgimpbase/gimpversion.h>
+
+G_BEGIN_DECLS
+
+/**
+ * GIMP_WARNING_API_BREAK:
+ * @message: the message to output either as build WARNING or ERROR.
+ *
+ * Internal macro to use when we consider an API break, so that we don't
+ * forget to look at it when the time comes:
+ *
+ * - When the minor version reaches 99 (e.g. 3.99), the message will be
+ *   outputted as a compilation warning.
+ * - When the minor and micro versions are 0.0 (e.g. 4.0.0), the message
+ *   will be outputted as compilation error, hence forbidding a major
+ *   release unless we resolve all the API break warnings (in any way,
+ *   it can be by actually breaking the API, or by deciding that this is
+ *   not a valid change anymore).
+ *
+ * Note: this macro relies on the "GCC warning" pragma which was tested
+ * to work on clang too. Assuming/hoping it works on other compilers.
+ **/
+
+#if GIMP_CHECK_VERSION(GIMP_MAJOR_VERSION, 99, 0)
+ #define GIMP_PRAGMA(pragma)       _Pragma(#pragma)
+ #define GIMP_WARNING_MSG(message) GIMP_PRAGMA(GCC warning #message)
+
+ #define GIMP_WARNING_API_BREAK(message) GIMP_WARNING_MSG(message)
+#elif GIMP_MINOR_VERSION == 0 && GIMP_MICRO_VERSION == 0
+ #define GIMP_PRAGMA(pragma)     _Pragma(#pragma)
+ #define GIMP_ERROR_MSG(message) GIMP_PRAGMA(GCC error #message)
+
+ #define GIMP_WARNING_API_BREAK(message) \
+    GIMP_ERROR_MSG("API break warning needs to be handled before releasing: " message)
+#else
+ #define GIMP_WARNING_API_BREAK(message)
+#endif
+
+
+G_END_DECLS
+
+#endif /* __GIMP_VERSION_PRIVATE_H__ */
diff --git a/plug-ins/common/compose.c b/plug-ins/common/compose.c
index e03bdbcbe2..e0ca83f6b0 100644
--- a/plug-ins/common/compose.c
+++ b/plug-ins/common/compose.c
@@ -41,6 +41,7 @@
 #include <libgimp/gimp.h>
 #include <libgimp/gimpui.h>
 
+#include "libgimpbase/gimpversion-private.h"
 #include "libgimp/stdplugins-intl.h"
 
 
@@ -1036,6 +1037,7 @@ compose (const gchar         *compose_type,
         }
     }
 
+  GIMP_WARNING_API_BREAK("Update 'decompose-type' choices? See discussion in MR !2424.")
   /* TODO: The strings used in decompose.c's "decompose-type" do not match
    * the values of compose_type for YCbCr values. We'll need to wait until
    * the next API break to fix. For now, we can do additional checks if the