config: boot defaults from CURRENT rather than STABLE

Which version a build uses when nothing has selected one was STABLE, the
most recently released schema.  That is the wrong answer for it.  A build
defaults to the schema it was written around, and between releases that
is the one under development, not the one the last release shipped.
Booting from STABLE makes every default a development branch changes
inert unless a config file opts in, which is backwards: the departures
are the point of a development branch.

Boot from CURRENT instead.  This needs no notion of whether the build is
a tagged release: at a release the two constants name the same schema, so
a release build boots the released defaults by the same rule, and they
part company again only as development resumes.

Nothing changes today, because the two schemas are still identical.  It
matters from the first key version 2 adds, and selecting version 1 keeps
working because a version resolves through its chain.

Assisted-by: Claude-Code:claude-opus-5
Signed-off-by: Zygo Blaxell <bees@furryterror.org>

diff --git a/docs/config-file.md b/docs/config-file.md
index da1f0a7a13e9c2fd8f69995cecfd8db3c3a7db73..2a31effa9f96e56152c0c05dfb479a253818b98e 100644 (file)
--- a/docs/config-file.md
+++ b/docs/config-file.md
@@ -21,11 +21,12 @@ overrides global, command-line overrides all).
 * **`version`**
   Locks the version of default values so upgrades do not silently change behavior.
   If an option’s default value changes in a new bees release, `config.version` must be bumped to pick it up.
+  Selecting a version pins the defaults of the keys it defines; keys added after it take the value they were introduced with, so pinning an old version stays possible as bees gains options.
   Accepted values:
 
   * Numeric version (e.g. `1`)
-  * `STABLE` – most recent released configuration version.  This _does_ change with new bees releases.  It is the default for tagged releases and release candidates.
-  * `CURRENT` – most recent development version.  This changes between bees releases in order to enable experimental new features.  It is the default for untagged development versions between releases.
+  * `STABLE` – most recent released configuration version.  This _does_ change with new bees releases.
+  * `CURRENT` – most recent development version.  This changes between bees releases in order to enable experimental new features.  It is what a build uses when no configuration selects a version; between releases that is a development version, and at a release it is the released one.
   * A release alias such as `v0.11` – the configuration version that the named release shipped.  Unlike `STABLE` and `CURRENT`, a release alias names a frozen version, so it keeps its meaning across upgrades.
 
 * **`global-config-filename`**
@@ -85,7 +86,7 @@ Note that this will enable the use of symlinks in the path as well.
 
 * Default layouts:
 
-  * Version: `STABLE`.  `CURRENT` must always be explicitly invoked.
+  * Version: `CURRENT`, the schema this build was written around.  Set `config.version` to `STABLE`, to a release alias such as `v0.11`, or to a number to pin the defaults of an earlier schema.
   * Global config filename: `/etc/bees/bees.conf`
   * Local config filename by UUID: `/etc/bees/uuid.d/${UUID}.conf`
 

diff --git a/src/bees-config.cc b/src/bees-config.cc
index 1fce8d13f1434d2aaa795c3ad9763cc23f394b6b..33a4cea7681c7c60f05988423f682975c15acb40 100644 (file)
--- a/src/bees-config.cc
+++ b/src/bees-config.cc
@@ -286,8 +286,13 @@ BeesConfig::set_argv(const Innie &startup_ini)
                default_version = resolved;
        };
 
-       // Load STABLE defaults for this build of bees
-       reset_default(s_stable_version);
+       // Load this build's own defaults, before any config file has had a
+       // chance to say which version it wants.  CURRENT rather than STABLE:
+       // what a build defaults to is the schema it was built around, and
+       // between releases that is the one under development.  At a release the
+       // two name the same schema, so a release build boots the released
+       // defaults without needing to know it is a release.
+       reset_default(s_current_version);
 
        // "config.version" now has a default.
        // Find out what version of defaults to use

diff --git a/src/bees-config.h b/src/bees-config.h
index 55aa03673e579ad156f77458c9c9a262b8d5375b..621cb4c713a7c23f9a2a8d6c1e23c78b3d0382f1 100644 (file)
--- a/src/bees-config.h
+++ b/src/bees-config.h
@@ -49,10 +49,13 @@ class BeesConfig {
        /// Newest config schema in this build: the one under development, and
        /// what CURRENT resolves to.
        static constexpr const char *s_current_version = "2";
-       /// Oldest config schema that is still fully compatible with this build,
-       /// and what STABLE resolves to.  Version 1 is frozen at what v0.11
-       /// shipped; it stays compatible for as long as version 2 defines no key
-       /// that version 1 lacks.
+       /// Most recently released config schema, and what STABLE resolves to.
+       /// Version 1 holds the defaults that reproduce v0.11 behaviour.  It may
+       /// come to define fewer keys than this build queries, and stays
+       /// selectable anyway because a version resolves through version_chain():
+       /// the keys added since come from the schemas that added them.  At a
+       /// release the two constants meet again, and part company as development
+       /// resumes.
        static constexpr const char *s_stable_version = "1";
 
        /** \brief What a version alias resolves to, and whether it can move.