Found during review of #178 (T2-4).
tycoon init --upgrade and the schema_version field in tycoon.yml are both user-facing and both undocumented. Neither appears anywhere in docs/ or CHANGELOG.md — the only matches for "schema_version" are dbt_schema_version and schema_version_hash in docs/reference/observability.md, which are unrelated dlt/dbt fields.
This matters more than a normal docs gap: --upgrade is the remedy named in the warning users will actually see.
WARN tycoon.yml is at schema version none, current is 2. Run 'tycoon init --upgrade' to migrate.
A user who follows that instruction has nowhere to read what it will do to their file.
Scope
schema_version in the tycoon.yml reference — what it is, that tycoon manages it, that it is distinct from the user's own version: field (a genuinely confusable pair)tycoon init --upgrade in the CLI reference — what it changes, that it preserves comments and formatting, that it is idempotent- CHANGELOG entry for v0.1.11
docs/log.md + the relevant index.md, per the OKF convention
Note
T2-2 introduced schema_version without docs as well, so this covers the whole M2 schema surface rather than just the --upgrade flag.
Mirrored in Jira: PTC-113 (Subtask of PTC-84, [Rewrite M2]). Dev work continues here.
Found during review of #178 (T2-4).
tycoon init --upgradeand theschema_versionfield intycoon.ymlare both user-facing and both undocumented. Neither appears anywhere indocs/orCHANGELOG.md— the only matches for "schema_version" aredbt_schema_versionandschema_version_hashindocs/reference/observability.md, which are unrelated dlt/dbt fields.This matters more than a normal docs gap:
--upgradeis the remedy named in the warning users will actually see.A user who follows that instruction has nowhere to read what it will do to their file.
Scope
schema_versionin thetycoon.ymlreference — what it is, that tycoon manages it, that it is distinct from the user's ownversion:field (a genuinely confusable pair)tycoon init --upgradein the CLI reference — what it changes, that it preserves comments and formatting, that it is idempotentdocs/log.md+ the relevantindex.md, per the OKF conventionNote
T2-2 introduced
schema_versionwithout docs as well, so this covers the whole M2 schema surface rather than just the--upgradeflag.Mirrored in Jira: PTC-113 (Subtask of PTC-84, [Rewrite M2]). Dev work continues here.