Repository navigation
Decision 0015: operator facing commands carry the Keel name - #3
Conversation
The Keel name becomes the real command and the turnkey-* name is kept as a symlink to it, both working, as a general policy rather than a per-appliance choice. Compatibility with TurnKey is a stated property of this project (0008), so an operator who pasted a command out of TurnKey's documentation, or who wrote a script against turnkey-wp last year, must not silently lose it. The note says which of tracker#12's commands the policy moves now and which wait, and corrects two things in that table. turnkey-php and turnkey-mysql-install-perf-info-schemas are called inherited there; they are ordinary files in the common repository of this organization, reaching the image through COMMON_OVERLAYS, so the policy applies to them in full and what makes them wait is the rebuild of the whole chain, not ownership. And turnkey-sysinfo ships turnkey-detect-virt as well, which the table missed. A turnkey-* name owned by a Debian package is out of scope here. It is settled by owning the package: the maintainer decided on 2026-09-28 to build keel-version and keel-sysinfo as Keel's own source packages rather than wrap or divert TurnKey's, which is tracker#13. The pair is a closed set, which is what makes that possible: turnkey-sysinfo 1.1.0 has no reverse dependencies and turnkey-version 1.1.3's only one is turnkey-sysinfo. The note also records which symlink mechanism was verified and how. The link is committed into the overlay, because fab-apply-overlay is cp -TdR and -d keeps a link a link, and that was checked by making the copy and running the copied command rather than by reading the flag.
ReviewI checked the note's factual claims against fab's source, this organization's repositories and the booted Verified
HIGH — the table omits five commands that the note's own scope rule pulls in, and they ship on every applianceLines 15-20 against the table at 66-72. The rule is: the policy applies to "every operator facing command a repository of this organization writes and names itself: a file in an appliance overlay, a file in the Measured on the booted
Both packages carry a Meanwhile the row the table does devote to packages sends The scenario this bites in is the one the note is written to prevent. A contributor picks up tracker#12, reads 0015 as the settled scope, sees The fix is small — either add the rows, or add one sentence saying the table covers the commands reachable from tracker#12's inventory and that packaged commands from MEDIUM — the
|
… the cp claim Review of #3 raised one HIGH: the note's inventory contradicted the note's own scope rule, and in the direction that makes a contributor under-apply the policy. The rule covers "a script installed by a package this project builds"; the table listed only the two keel-wordpress overlay files, the two in common and the foreign packages going to tracker#13. So it handled somebody else's packages and silently dropped the ones we build. Five commands were missing, all shipping on every appliance: turnkey-init, turnkey-sudoadmin, turnkey-install-security-updates and bin/turnkey-init-fence from inithooks, and turnkey-lexicon from confconsole. Both packages carry a +keel version, both are built from this organization's forks, and keel-wordpress's Makefile already names them among "the project's own packages". turnkey-init is the most operator-facing command on the machine. Two more were missing from common, turnkey-artisan and turnkey-composer, in scope by the rule though nothing includes laravel.mk or composer.mk yet; and unit-mariadb carries a byte-identical second copy of turnkey-mysql-install-perf-info-schemas, same blob, which the table attributed to common alone, so anybody following it would rename one of two copies. The inventory is now fifteen names grouped by what puts the file on the machine, because that is what decides when each can move, with eleven marked as ours. turnkey-make-ssl-cert from turnkey-ssl is listed too, as explicitly out of scope, so the next reader does not have to work that out again. And the section closes by saying the rule wins when the two disagree, since a table is a measurement of one day and this one has now been corrected three times. Second finding, a factual error worth more here than in code because a note is applied without asking: -d is not what preserves the symlink. -P is already the default under -R and only -L dereferences, so what -d buys is --preserve=links, which is hard links. As written the note would have taught that a copy without -d flattens links. Corrected with the measurement, and keel-wordpress now asserts the real property. Also from the review: the Decision section says the link is relative and why an absolute one breaks the build time caller, and that the Keel name is the turnkey- prefix replaced by keel- and nothing else, both of which were open questions a reader would have had to guess; the Consequences bullet about tests says "must be covered" rather than describing a state that is true of one repository; and the reverse dependency provenance says the container throughout rather than switching to the build host mid-section.
Re-reviewI re-measured the inventory rather than reading the new tables, and checked the two claims that carry weight. The HIGH is resolvedThe five commands from packages this project builds are in, as their own group, with the Re-measured independently and the arithmetic holds. Fifteen distinct names, eleven ours: The blob claim is exact. The
"When the table and the rule disagree, the rule wins" — genuine, on this evidenceI was ready to read that as a way to keep shipping a wrong table, and on its own it would be. It is not on its own. It arrives with a table that went from five names to fifteen, a stated grouping principle (by what puts the file on the machine, because that is what decides when each can move), and an instruction rather than an excuse: "the right fix is to add the row". A precedence clause that licenses inaction looks different — it appears instead of a measurement, not after a better one. The clause is also just true. A table is a measurement of one day and this one will go stale the next time a repository gains a command; a policy whose scope is defined by an enumeration is a policy that silently shrinks. Putting the rule above the table is what stops that. What would make it self-correcting rather than merely honest is the one thing still missing, and it is a LOW suggestion, not a condition. Nothing re-measures. The Consequences bullet already says finding these is The
|
Brief section 10 asks for commas, colons, parentheses or semicolons in documentation; the note carried fourteen em dashes. Wording otherwise unchanged.
…ommands Decision 0015: operator facing commands carry the Keel name
1 participant
Cross-reference only, nothing is closed from here: Keel-Linux/tracker#12 is the org-wide issue, and the implementation lives in its own repository issue, Keel-Linux/keel-wordpress#7, with Keel-Linux/keel-wordpress#6 as its pull request. The handbook carries the policy and nothing else.
Merge this before Keel-Linux/keel-wordpress#6, which cites decision 0015 in its
changelog,COVERAGE.md,tests/wrappers.batsand both script headers.docs/decisions/0015-operator-command-names.mdrecords the rule the maintainer decided on 2026-09-28: the Keel name is the real command, theturnkey-*name is kept as a symlink to it, and both keep working. It is a general policy, not a per-appliance choice, and the reason for keeping the old name is the same one that keeps/etc/turnkey_versionin 0014 — compatibility with TurnKey appliances is a stated property of this project (0008).Responding to the review
HIGH — the inventory contradicted the note's own scope rule. Correct, and it did so in the direction that makes a contributor under-apply the policy. The rule covers "a script installed by a package this project builds"; the table listed only the two keel-wordpress overlay files, the two in
common, and the foreign packages going to tracker#13. So the note handled somebody else's packages and silently dropped the ones we build.I verified the five myself against the dpkg file lists and against the forks' own trees, and added them:
/usr/sbin/turnkey-initinithooks 2.3.6+keel4Keel-Linux/inithooks,turnkey-init/usr/sbin/turnkey-sudoadmininithooks 2.3.6+keel4Keel-Linux/inithooks,turnkey-sudoadmin/usr/sbin/turnkey-install-security-updatesinithooks 2.3.6+keel4Keel-Linux/inithooks,turnkey-install-security-updates/usr/lib/inithooks/bin/turnkey-init-fenceinithooks 2.3.6+keel4Keel-Linux/inithooks,bin/turnkey-init-fence/usr/bin/turnkey-lexiconconfconsole 2.2.3+keel2Keel-Linux/confconsole,turnkey-lexiconAlso added, from LOW 1:
turnkey-artisanandturnkey-composer, tracked100755files incommonreached throughlaravel.mkandcomposer.mk; and the byte-identical second copy ofturnkey-mysql-install-perf-info-schemasinunit-mariadb(same blobc8f185b2), which the old table attributed tocommonalone, so anybody following it would have renamed one of two copies.turnkey-make-ssl-certfromturnkey-ssl 3.1.1is now listed too, explicitly out of scope, so the next reader does not have to derive that again.The section is restructured: fifteen distinct names grouped by what puts the file on the machine — appliance overlay,
commonoverlay, a package we build, a package somebody else builds — because that is what decides when each one can move. Eleven are ours.turnkey-init-fenceis marked as not onPATHand not a command an operator types, with the observation that the same name is also a conffile, a systemd unit and two firstboot hooks, which is a packaging question the note does not settle. And the section now closes by saying that when the table and the rule disagree, the rule wins — a table is a measurement of one day and this one has been corrected three times.I took the reviewer's framing on the
+keelsuffix: the rule reads on "a package this project builds", andturnkey-sysinfo1.1.0,turnkey-version1.1.3 andturnkey-ssl3.1.1 carry no such suffix whileinithooksandconfconsoledo. The "what a package owns does instead" section now opens by saying it is about packages we do not build, since getting that the wrong way round is precisely the mistake the first version made.MEDIUM — the
-dclaim. Correct, and worse in a note than in code, because a note is applied without asking. Measured with coreutils 9.7 and written into the note as a table:The property is the absence of
-L, not the presence of-d. keel-wordpress#6 now has a test asserting all three rows, so the claim is checked rather than written down.LOW 2 — the Decision section now states that the link is relative and why an absolute one breaks the build-time caller, and that the Keel name is the
turnkey-prefix replaced bykeel-and nothing else. LOW 3 — "must be covered", and it names who is owed those tests. LOW 4 — the reverse-dependency provenance says the container throughout. LOW 5 — merge order is stated at the top of both pull request descriptions.Test plan
Date,Status,## Decision, the three-part justification of brief section 10,## Consequences.dpkg -L/dpkg -Sfile lists,git ls-filesacross the organization's repositories, and the.mkfiles that pull each overlay.+keelversion.This repository ships no package and has no
package / changeloggate, so there is no changelog entry to add, and no checks are reported on the branch.