docs: document the customization surface#2
Merged
Merged
Conversation
Add a "Customizing" section to README.md covering the three things a user
of this template may change: registry/owners.txt (required), the agent and
model pinned in extension.toml.in, and the name `fleet`.
`fleet` names the session, not the user, and keeping it is a fine default.
Because it is hardcoded in six coupled places, the section maps them so a
reader can see they move together, and names the failure mode of a partial
rename: the extension installs under the new name while worker briefs still
mail `--to fleet`, so results never reach the lead.
Also correct a stale claim, in extension.toml.in's header, README.md, and
scripts/install-extension.sh: the tilde-expansion bug is fixed (thurbox#782,
first shipped in 0.174.2). The `__REPO_PATH__` placeholder still stands, for
two reasons now stated explicitly — `min_thurbox_version` is 0.113.0, which
predates the fix, and independently of the bug no token resolves to the
user's checkout, since `{home}` is the extension home.
Documentation only: extension.toml.in's TOML keys are unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents what a user of this template may change, and corrects a claim that has gone stale.
The name
fleetis hardcoded in six coupled places, and nothing told a reader whether they could change it. The new Customizing section inREADME.mdsays plainly thatfleetnames the session — not the user, not the repo — so keeping it is a good default rather than a setup step people have missed. It maps the six places so they can be seen to move together, names the failure mode of a partial rename (the extension installs under the new name while every worker brief still mails--to fleet), and folds in the two customization points that existed but were only mentioned in passing: the pinned model/agent, andregistry/owners.txt.Separately,
extension.toml.inclaimed the tilde-expansion bug was "unfixed as of this writing". thurbox#782 fixed it, first shipping in 0.174.2. The__REPO_PATH__placeholder still has to stay, so the comment is corrected rather than deleted:min_thurbox_versionis0.113.0, which predates the fix, and — independently of the bug — no token resolves to the user's checkout, since{home}is the extension home. The same stale reasoning appeared inREADME.mdand inscripts/install-extension.sh's header; both are fixed the same way.Documentation only.
extension.toml.in's TOML keys are byte-identical (git diffon non-comment lines is empty);shellcheck scripts/*.shis clean.One thing worth a look: the brief said
fleetappears in six places and to flag a seventh. There is one — the worker naming conventionfleet-<slug>inorchestration/playbooks/andorchestration/runs/_TEMPLATE.md. It is not coupled (worker session names are free-form strings nothing resolves), so the section documents it as safe to leave alone.