config: say version 1 is being frozen, not that it is frozen

The banner on version 1 claimed two things that are not yet true.  It
said FROZEN, when the release that would freeze it has not happened: the
schema is being frozen, and settling what it says -- wording that
describes a feature since removed, a default that turns out not to match
the release it stands for -- is what freezing consists of.  Declaring it
finished discourages exactly the corrections this stage is for.

It also called version 1 the schema v0.11 shipped.  v0.11 had no
configuration file at all; the INI schema has never been released.
Version 1 is a statement about how v0.11 behaved, expressed as defaults,
so that an installation upgrading from it keeps the behaviour it had.
That is a claim about behaviour, and it can be got wrong and corrected,
which the old wording left no room for.

Say both plainly, and say what changes at the release: after it, an
installation's defaults resolve through this file, and editing a value
changes what it gets on its next upgrade.

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

diff --git a/src/bees-config-v1.cc b/src/bees-config-v1.cc
index 3028ead1778d4edb37aa8dbde2b81c43d280345f..b308b27e39d1ef9fa798c73ddfdce4475ba65190 100644 (file)
--- a/src/bees-config-v1.cc
+++ b/src/bees-config-v1.cc
@@ -1,12 +1,21 @@
 #include "bees-config.h"
 
-// FROZEN.  This is the schema bees v0.11 shipped, kept so an installation can
-// go on resolving the defaults it has been running (config.version = 1, or the
-// v0.11 alias).  The values here are a record of a past release rather than a
-// starting point: editing one changes what an already-deployed installation
-// resolves to the next time it upgrades, which is the one thing versioning the
-// schema exists to prevent.  New options and changed defaults belong in the
-// highest-numbered bees-config-v*.cc.
+// Version 1 of the built-in configuration schema: the defaults that reproduce
+// how bees v0.11 behaved, so an installation upgrading from that release keeps
+// the behaviour it had.  v0.11 had no configuration file at all, so this is a
+// statement about that release's behaviour rather than a copy of anything it
+// shipped, and it is selected as config.version = 1 or by the v0.11 alias.
+//
+// This schema is being frozen for the coming release; it is not frozen yet.
+// Until that release goes out, correcting what it says here is part of getting
+// it right -- wording that describes a feature since removed, a default that
+// turns out not to match v0.11, and so on.  Afterwards, installations resolve
+// their defaults through this file, and changing a value here changes what
+// they get on their next upgrade, which is the one thing versioning the schema
+// exists to prevent.
+//
+// New options and changed defaults belong in the highest-numbered
+// bees-config-v*.cc either way.
 static const char bees_config_v1[] = R"--v1-config--(
 
 # The [config] section controls config file sources and versioning.

diff --git a/src/bees-config-v2.cc b/src/bees-config-v2.cc
index 0aa4af1e65827fd716a9089a47268a538fee44dd..1d197e46dde2f5d3135bcabec8813df032bfeea6 100644 (file)
--- a/src/bees-config-v2.cc
+++ b/src/bees-config-v2.cc
@@ -13,5 +13,6 @@ static const char bees_config_v2[] = R"--v2-config--(
 )--v2-config--";
 
 // Schema version 2 is the one under development: new options and changed
-// defaults land here.  bees-config-v1.cc is frozen at what v0.11 shipped.
+// defaults land here.  bees-config-v1.cc is being frozen at the defaults that
+// reproduce v0.11 behaviour.
 static BeesConfig::Register s_reg_config_v2("2", "v0.11", bees_config_v2);