Give the runbook the new-table case, and separate the two rebuilds - #8
Merged
Conversation
An estate using a table glob meets one operational case before any other: a table created since the last generate is not granted, and every run since has reported success. The runbook had no entry for it. 3i covers why the skip holds, what `rebuild=True` re-resolves and drops, holding one back with `exclude_tables`, the stale converse when a table is deleted, and the unrelated conditions that force a re-resolution and widen scope as a side effect. The sharper problem is the word itself. `rebuild` appeared in the runbook in exactly one place — 3e, `setup(rebuild=True)`, which DROPS a control table and loses its data. So an operator whose new table is missing, searching the runbook for `rebuild`, found the destructive one and no sign that a harmless one exists. 3e now says the two share a name and nothing else, and points next door. Both sections say plainly that not granting a table is not denying it: readability still depends on workspace and item permissions, and a missing grant must not be read as containment.
Follow-up review of the same claim across the repo turned up two more. The cookbook's generate note told readers that re-running an unchanged config is a no-op — true, and the half nobody is surprised by. The half that surprises them is that a changed CATALOG is also a no-op, which is exactly the case the new runbook section exists for. It now says both and points there. `config-examples.md`'s CLS whitelist takeaway said the difference "only shows up on a later generation" — the same ambiguity 7a lost two sections earlier in the previous commit, left behind in 7b because the sweep matched on wildcards rather than on the shape of the claim.
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
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.
Follow-up to #7, which added
rebuildto the master workflow and documented the skip inmodes.md. The reference docs now describe the behaviour; the runbook — where an operator actually goes when something looks wrong — still did not.The case that was missing
An estate using a table glob meets this before any other: a table created since the last generate is not granted, and every run since has reported success. Nothing in the runbook explained that.
New 3i covers:
config_hashfingerprints config rows and cannot see the catalogrebuild=Truere-resolves every pattern, so it takes in every table added since the last real generate, not only the one you had in mind — read the plan, not the config diffexclude_tables, and that a zero-match exclude is an error (rule A2), so the table must already existThe sharper problem: one word, two opposite meanings
rebuildappeared in the runbook in exactly one place — 3e,setup(rebuild=True), which DROPS a control table and loses its data.So an operator whose new table is missing, searching the runbook for
rebuild, found the destructive one and no sign that a harmless one exists. 3e now states that the two share a parameter name and nothing else, and points at 3i.Safety language
Both sections say plainly that not granting a table is not denying it — readability still depends on workspace and item permissions and the access path, so a missing grant must not be read as containment. This matches the framing
modes.mdandarchitecture.mdalready use.Verification
check_public_release.py tree .— PASS, 0 findingscheck_external_links.py— 40/40 reachable[Unreleased].