config: fork schema version 2, begin freezing version 1

Config schema version 1 is the set of defaults that reproduce how bees
v0.11 behaved.  That release shipped no configuration file, so version 1
is a statement about its behaviour rather than anything it published, and
installations upgrading from it resolve their defaults through version 1.
Editing it is therefore not a local change once a release has gone out:
every default touched there silently changes what an already-deployed
installation gets on its next upgrade, which is precisely what versioning
the schema exists to prevent.  Version 1 has nevertheless been the only
schema, so it has also been where new development lands.

Split the two roles.  bees-config-v2.cc is forked from version 1 and
becomes the schema under development; version 1 keeps the values it has
and gains a banner saying so.

CURRENT now resolves to 2, so it names the development schema as
documented.  STABLE stays at 1: version 1 remains fully compatible for as
long as version 2 defines no key that version 1 lacks, and it is the
schema that stands for the most recent release.

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

diff --git a/src/Makefile b/src/Makefile
index ea5b87a31ed39fd74729fa5889aade8e123c461c..1f8536fde36c5c0929b95b777fa53dec9a3e7532 100644 (file)
--- a/src/Makefile
+++ b/src/Makefile
@@ -21,6 +21,7 @@ BEES_LDFLAGS = -L../lib $(LDFLAGS)
 BEES_OBJS = \
        bees.o \
        bees-config-v1.o \
+       bees-config-v2.o \
        bees-config.o \
        bees-usage.o \
        bees-context.o \

diff --git a/src/bees-config-v1.cc b/src/bees-config-v1.cc
index 15a55020e65f790b3a59a493da361c22f9aad768..285724551eafc9102a54710e2286bfaefb0fdafb 100644 (file)
--- a/src/bees-config-v1.cc
+++ b/src/bees-config-v1.cc
@@ -1,5 +1,12 @@
 #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.
 static const char bees_config_v1[] = R"--v1-config--(
 
 # The [config] section controls config file sources and versioning.
@@ -126,34 +133,27 @@ static const char bees_config_v1[] = R"--v1-config--(
 
 [report.*]
 
-        # Whether this report output is active.
-        # Both active = yes and a non-empty filename are required to write.
-        # The $BEESSTATUS environment variable overrides report.legacy.filename
-        # and activates report.legacy regardless of this key.
+        # Whether this report output is active.  yes/no.
+        # Writing also requires a non-empty filename.
         active = no
 
         # Target interval between rewrites of this report file.
         # Minimum: 0.1s.
         interval = 1s
 
-        # Final permission mode for the report file (octal).
-        # Applied via fchmod after writing, before the atomic rename into place.
-        # Write bits are never needed: report files are always written via a
-        # temporary file and renamed into place atomically.
+        # Permission mode for the report file (octal).
         mode = 0400
 
         # syslog-style level (0=EMERG ... 6=INFO, 7=DEBUG) used when the report
         # is emitted to the log (filename = -).  Ignored for file reports.
         level = 6
 
-        # Owner of the report file.  Accepts a name or numeric uid.
-        # Resolved to a uid once at startup; an unknown name is a config error.
-        # Empty = no chown; file is owned by the bees process user.
+        # Owner of the report file: a name, a numeric uid, or empty for no
+        # chown.  A leading ':' forces a name lookup (e.g. ':1000').
         user =
 
-        # Group of the report file.  Accepts a name or numeric gid.
-        # Resolved to a gid once at startup; an unknown name is a config error.
-        # Empty = no chown; file is owned by the bees process group.
+        # Group of the report file: a name, a numeric gid, or empty for no
+        # chown.  A leading ':' forces a name lookup (e.g. ':1000').
         group =
 
         # Filename of the report file.
@@ -307,10 +307,7 @@ static const char bees_config_v1[] = R"--v1-config--(
         persistent = yes
 
         # Auto-create path.home and beeshash.dat if they do not exist.
-        # When yes, bees creates the path.home directory at startup if
-        # it is missing.  When no, startup fails if path.home or
-        # beeshash.dat is missing.
-        # Has no effect when state.persistent = no.
+        # Set to no to require both to be present at startup.
         create = yes
 
 # The [state.hash] section controls hash table file options.

diff --git a/src/bees-config-v2.cc b/src/bees-config-v2.cc
new file mode 100644 (file)
index 0000000..b6d8921
--- /dev/null
+++ b/src/bees-config-v2.cc
@@ -0,0 +1,13 @@
+#include "bees-config.h"
+
+static const char bees_config_v2[] = R"--v2-config--(
+[config]
+
+        # Config version (number) or alias (STABLE, CURRENT, v0.11).
+        version = 2
+
+)--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.
+static BeesConfig::Register s_reg_config_v2("2", bees_config_v2);

diff --git a/src/bees-config.h b/src/bees-config.h
index 2a1d6093d81e81d22d116b61958de1ca73fcf156..73df51a5bfdd4aaac8c664fd76d77de5918b429a 100644 (file)
--- a/src/bees-config.h
+++ b/src/bees-config.h
@@ -40,9 +40,13 @@ class BeesConfig {
        /// Map of version string -> built-in default INI text.
        using DefaultMap = map<string, Innie>;
        static unique_ptr<DefaultMap> s_defaults;
-       /// Version of the config schema currently in use.
-       static constexpr const char *s_current_version = "1";
-       /// Oldest config schema version that is fully compatible.
+       /// 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.
        static constexpr const char *s_stable_version = "1";
 
        /** \brief Named aliases accepted wherever a config schema version is.

diff --git a/test/test-bees-point.cc b/test/test-bees-point.cc
index 887daab10ae8f4c4f8a314a73757d90fa8262530..163e436934606f1144fbfcfb4fe3af418532d1ba 100644 (file)
--- a/test/test-bees-point.cc
+++ b/test/test-bees-point.cc
@@ -35,7 +35,7 @@ static const set<string> s_known_extent_tiers {
        "max",
 };
 
-/// Expected legacy-id for each tier (matches bees-config-v1.cc).
+/// Expected legacy-id for each tier (matches bees-config-v2.cc).
 static const map<string, uint64_t> s_expected_legacy_id {
        { "128K", 255 },
        { "512K", 254 },
@@ -265,7 +265,7 @@ test_legacy_import_roundtrip()
        bcs.m_max_transid = d.at("max_transid");
        bcs.m_started     = d.at("started");
 
-       // Build legacy_id_to_name from a synthetic config (mirrors bees-config-v1.cc).
+       // Build legacy_id_to_name from a synthetic config (mirrors bees-config-v2.cc).
        // In production, import_legacy() reads from m_ctx->get_config().sections().
        const string config_text =
                "[scan.extent.*]\n"
@@ -373,7 +373,7 @@ static
 void
 test_config_legacy_ids()
 {
-       // Mini config that replicates the [scan.extent.*] sections from bees-config-v1.cc.
+       // Mini config that replicates the [scan.extent.*] sections from bees-config-v2.cc.
        const string config_text =
                "[scan.extent.*]\n    active = yes\n    method = 0\n"
                "[scan.extent.128K]\n    legacy-id = 255\n"