docs: user/site: improve feature flag explanation

docs/user/site.rst

@@ -475,21 +475,72 @@ GLUON_WLAN_MESH
   support both meshing modes, either at all (e.g. ralink and mediatek don't support AP+IBSS) or in the
   same firmware (ath10k-based 5GHz). Defaults to ``11s``.
 
-Features
-^^^^^^^^
-
-Each package starting with "gluon-" can be included as a feature _flag_ by
-omitting the prefix "gluon-"; for example, the flag *mesh-batman-adv-15* will
-include only the package *gluon-mesh-batman-adv-15*.
-
-Some flags are specially treated (for example `web-wizard` and `web-advanced`)
-and can contain more than one package. Those are defined in the config file
-`package/features`. Please read that file for more details.
-
-Site-provided package feeds can define additional feature flags. To use own
-package feeds to define your own features, add a file `gluon/features` to your
-site folder.
-
+.. _user-site-feature-flags:
+
+Feature flags
+^^^^^^^^^^^^^
+
+With the addition of more and more features that interact in complex ways, it
+has become necessary to split certain packages into multiple parts, so it is
+possible to install just what is needed for a specific usecase. One example
+is the package *gluon-status-page-mesh-batman-adv*: There are batman-adv-specific
+status page components; they should only be installed when both batman-adv and
+the status page are enabled, making the addition of a specific package for this
+combination necessary.
+
+With the ongoing modularization, e.g. for the purpose of supporting new
+routing protocols, specifying all such split packages in *site.mk* would
+soon become very cumbersome: In the future, further components like
+respondd support or languages might be split off as separate packages,
+leading to entangled package names like *gluon-mesh-vpn-fastd-respondd* or
+*gluon-status-page-mesh-batman-adv-i18n-de*.
+
+For this reason, we have introduced *feature flags*, which can be specified
+in the *GLUON_FEATURES* variable. These flags allow to specify a set of features
+on a higher level than individual package names.
+
+Most Gluon packages can simply be specified as feature flags by removing the ``gluon-``
+prefix: The feature flag corresponding to the package *gluon-mesh-batman-adv-15* is
+*mesh-batman-adv-15*.
+
+The file ``package/features`` in the Gluon repository (or
+``features`` in site feeds) can specify additional rules for deriving package lists
+from feature flags, e.g. specifying both *status-page* and either *mesh-batman-adv-14*
+or *mesh-batman-adv-15* will automatically select the additional package
+*gluon-status-page-mesh-batman-adv*. In the future, selecting the flags
+*mesh-vpn-fastd* and *respondd* might automatically enable the additional
+package *gluon-mesh-vpn-fastd-respondd*, and enabling *status-page* and
+*mesh-batman-adv-15* (or *-14*) with ``de`` in *GLUON_LANGS* could
+add the package *gluon-status-page-mesh-batman-adv-i18n-de*.
+
+In short, it is not necessary anymore to list all the individual packages that are
+relevant for a firmware; instead, the package list is derived from a list of feature
+flags using a flexible ruleset defined in the Gluon repo or site package feeds.
+To some extent, it will even allow us to further modularize existing Gluon packages,
+without necessitating changes to existing site configurations.
+
+It is still possible to override such automatic rules using *GLUON_SITE_PACKAGES*
+(e.g., ``-gluon-status-page-mesh-batman-adv`` to remove the automatically added
+package *gluon-status-page-mesh-batman-adv*).
+
+For convenience, there are two feature flags that do not directly correspond to a Gluon
+package:
+
+* web-wizard
+
+  Includes the *gluon-config-mode-...* base packages (hostname, geolocation and contact info),
+  as well as the *gluon-config-mode-autoupdater* (when *autoupdater* is in *GLUON_FEATURES*),
+  and *gluon-config-mode-mesh-vpn* (when *mesh-vpn-fastd* or *mesh-vpn-tunneldigger* are in
+  *GLUON_FEATURES*)
+
+* web-advanced
+
+  Includes the *gluon-web-...* base packages (admin, network, WiFi config),
+  as well as the *gluon-web-autoupdater* (when *autoupdater* is in *GLUON_FEATURES*)
+
+We recommend to use *GLUON_SITE_PACKAGES* for non-Gluon OpenWrt packages only and
+completely rely on *GLUON_FEATURES* for Gluon packages, as it is shown in the
+example *site.mk*.
 
 .. _site-config-mode-texts: