]> git.hungrycats.org Git - bees/commitdiff
config: write down version 2's delta discipline
authorZygo Blaxell <bees@furryterror.org>
Mon, 31 Aug 2026 00:42:45 +0000 (20:42 -0400)
committerZygo Blaxell <bees@furryterror.org>
Tue, 6 Oct 2026 05:51:40 +0000 (01:51 -0400)
Version 2 states only what it changes from version 1; everything else
resolves along the inheritance chain.  Nothing in the file said so, which
left the next person adding an option no way to tell whether to edit the
value in version 1 or state a new one here -- and one of those silently
changes what an already-deployed installation resolves to the next time
it upgrades, which is the one thing versioning the schema exists to
prevent.

Write the rule down where the mistake would be made: what belongs here,
what does not, and the case that is easy to get wrong.  A key whose value
matches version 1 but whose comment does not still belongs here, because
the comment is part of what a schema states and is what --show-config
hands the operator.

Version 2 currently states one key, its own version number, which is what
a delta over a schema it does not yet differ from looks like.  The
trailing comment at the registration shrinks to a pointer, since the file
comment now says all of it in one place.

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

index 1d197e46dde2f5d3135bcabec8813df032bfeea6..a5b77520fd9afd013c897dad51f0ae746e75e87d 100644 (file)
@@ -1,5 +1,29 @@
 #include "bees-config.h"
 
+// Version 2 of the built-in configuration schema, and the one under
+// development: new options and changed defaults land here.
+//
+// This file is a delta.  It carries only what version 2 states differently
+// from the schema it inherits from -- a new option, a changed default, or a
+// changed comment -- and everything else resolves along the inheritance chain
+// to bees-config-v1.cc, which holds the defaults that reproduce v0.11
+// behaviour.  A key that would only repeat what version 1 already says
+// does not belong here: it would be a second copy of a value with nothing
+// holding the two in step.  Section headers appear only where this version
+// has something of its own to say, or where one is needed to hold a key
+// that does.
+//
+// So changing an existing default means adding that key here, not editing it
+// in version 1, and a key already listed here is one this version has taken a
+// position on.  A key whose value matches version 1 but whose comment does not
+// still belongs here: the comment is part of what a schema states, and it is
+// what --show-config hands the operator.
+//
+// Built-in config comments are a compact option reference.  Keep them focused
+// on option semantics, accepted values, defaults, and direct effects.  Put use
+// cases, examples, tradeoffs, and background explanation in user docs instead.
+// Keep option names and semantics aligned with docs/config-file.md and parser
+// code when changing configuration behavior.
 static const char bees_config_v2[] = R"--v2-config--(
 
 # The [config] section controls config file sources and versioning.
@@ -12,7 +36,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 being frozen at the defaults that
-// reproduce v0.11 behaviour.
+// Inherits from the schema that reproduces v0.11 behaviour; see the file
+// comment above.
 static BeesConfig::Register s_reg_config_v2("2", "v0.11", bees_config_v2);