introduce a basic module lifecycle

Modules may now be marked as 'Deprecated' or 'Experimental' in
their <module_info> section. When configuring a build with either
of them, a warning will be issued in the output of ./configure.py.

Experimental modules won't be built by default and may be enabled
either explicitly via --enable-modules or globally (all-at-once) with
--enable-experimental-features.

Deprecated modules are built by default but are scheduled for
removal in a future release of the library.

configure.py

@@ -951,9 +951,12 @@ def _parse_module_info(self, lex):
         self.name = info["name"]
         self.brief = info.get("brief") # possibly None
         self.type = info.get("type") or "Public"
+        self.lifecycle = info.get("lifecycle") or "Stable"
 
         if self.type not in ["Public", "Internal", "Virtual"]:
             raise InternalError("Module '%s' has an unknown type: %s" % (self.basename, self.type))
+        if self.lifecycle not in ["Stable", "Experimental", "Deprecated"]:
+            raise InternalError("Module '%s' has an unknown lifecycle status: %s" % (self.basename, self.lifecycle))
 
     @staticmethod
     def _validate_defines_content(defines):
@@ -1170,6 +1173,15 @@ def is_internal(self):
     def is_virtual(self):
         return self.type == "Virtual"
 
+    def is_stable(self):
+        return self.lifecycle == "Stable"
+
+    def is_experimental(self):
+        return self.lifecycle == "Experimental"
+
+    def is_deprecated(self):
+        return self.lifecycle == "Deprecated"
+
 class ModulePolicyInfo(InfoObject):
     def __init__(self, infofile):
         super().__init__(infofile)
@@ -2411,6 +2423,12 @@ def _check_usable(self, module, modname):
         elif not module.compatible_compiler(self._ccinfo, self._cc_min_version, self._archinfo.basename):
             self._not_using_because['incompatible compiler'].add(modname)
             return False
+        elif module.is_deprecated() and not self._options.enable_deprecated_features:
+            self._not_using_because['deprecated'].add(modname)
+            return False
+        elif module.is_experimental() and modname not in self._options.enabled_modules and not self._options.enable_experimental_features:
+            self._not_using_because['experimental'].add(modname)
+            return False
         return True
 
     @staticmethod
@@ -2428,13 +2446,27 @@ def _display_module_information_unused(cls, all_modules, skipped_modules):
     def _display_module_information_to_load(cls, all_modules, modules_to_load):
         sorted_modules_to_load = cls._remove_virtual_modules(all_modules, sorted(modules_to_load))
 
+        deprecated = []
+        experimental = []
         for modname in sorted_modules_to_load:
             if all_modules[modname].comment:
                 logging.info('%s: %s', modname, all_modules[modname].comment)
             if all_modules[modname].warning:
                 logging.warning('%s: %s', modname, all_modules[modname].warning)
             if all_modules[modname].load_on == 'vendor':
                 logging.info('Enabling use of external dependency %s', modname)
+            if all_modules[modname].is_deprecated():
+                deprecated.append(modname)
+            if all_modules[modname].is_experimental():
+                experimental.append(modname)
+
+        if deprecated:
+            logging.warning('These modules are deprecated and will be removed in a future release (consider disabling with --disable-deprecated-features): %s',
+                            ' '.join(deprecated))
+
+        if experimental:
+            logging.warning('These modules are experimental and may change or be removed in a future release: %s',
+                            ' '.join(experimental))
 
         if sorted_modules_to_load:
             logging.info('Loading modules: %s', ' '.join(sorted_modules_to_load))

doc/building.rst

@@ -75,6 +75,15 @@ want the resulting binary to depend on. For instance to enable zlib
 support, add ``--with-zlib`` to your invocation of ``configure.py``.
 All available modules can be listed with ``--list-modules``.
 
+Some modules may be marked as 'deprecated' or 'experimental'. Deprecated
+modules are available and built by default, but they will be removed in a
+future release of the library. Use ``--disable-deprecated-features`` to
+disable all of these modules or ``--disable-modules=MODS`` for finer grained
+control. Experimental modules are under active development and not built
+by default. Their API may change in future minor releases. Applications may
+still enable and use such modules using ``--enable-modules=MODS`` or using
+``--enable-experimental-features`` to enable all experimental features.
+
 You can control which algorithms and modules are built using the
 options ``--enable-modules=MODS`` and ``--disable-modules=MODS``, for
 instance ``--enable-modules=zlib`` and ``--disable-modules=xtea,idea``.

doc/dev_ref/configure.rst

@@ -213,6 +213,16 @@ Maps:
      * ``Virtual`` This module does not contain any implementation but acts as
        a container for other sub-modules. It cannot be interacted with by the
        library user and cannot be depended upon directly.
+   * ``lifecycle`` specifies the module's lifecycle (defaults to ``Stable``)
+
+     * ``Stable`` The module is stable and will not change in a way that would
+       break backwards compatibility.
+     * ``Experimental`` The module is experimental and may change in a way that
+       would break backwards compatibility. Not enabled in a default build.
+       Either use ``--enable-modules`` or ``--enable-experimental-features``.
+     * ``Deprecated`` The module is deprecated and will be removed in a future
+       release. It remains to be enabled in a default build. Either use
+       ``--disable-modules`` or ``--disable-deprecated-features``.
 
  * ``libs`` specifies additional libraries which should be linked if this module is
    included. It maps from the OS name to a list of libraries (comma seperated).

doc/sem_ver.rst

@@ -10,6 +10,11 @@ If on upgrading to a new minor version, you encounter a problem where your
 existing code either fails to compile, or the code behaves differently in some
 way that causes trouble, it is probably a bug; please report it on Github.
 
+Note that none of these guarantees apply to "experimental modules" that are not
+built by default. The functionality as well as API of such modules may change or
+even disappear in a minor version without warning. See :ref:`building` for more
+information on enabling or disabling these modules.
+
 Exception
 -----------------------