ckb/docs/decisions/0019-two-dot-zero-drops-powershell.md
Michał Kopeć 8415004031 Template 1.28.1: 1.x maintenance channel, major-version guard (D-0019)
Adds the `1.x` release channel (fixes only, last line with PowerShell
support) to every channel table, and makes ckb-upgrade stop and ask before
crossing a major version, offering the maintenance branch instead.
D-0019 records the 2.0 plan: drop PowerShell, scripts stay in Python.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 13:47:37 +01:00

4.4 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision Template 2.0.0 drops PowerShell (lint_quick.ps1 and every PowerShell snippet); scripts the template and its modules ship stay in Python; the 1.x line continues on a `1.x` maintenance branch for fixes, and ckb-upgrade never crosses a major version without asking. accepted 2026-11-11 Michał Kopeć .agents/skills/ckb-lint/, .agents/skills/ckb-upgrade/SKILL.md, .agents/skills/ckb-init/SKILL.md, .agents/skills/ckb-sync-changes/SKILL.md, AGENTS.md, README.md, docs/MANUAL.md, docs/CHANGELOG.md, VERSION 0.85 0.8 2026-11-11 365 high

D-0019 — 2.0 drops PowerShell; 1.x continues on a maintenance branch

Status: Accepted · Decided: 2026-11-11 · Deciders: Michał Kopeć

Supersedes only the PowerShell half of D-0003. Python as the single scripting runtime, interpreter resolution, the bash fallback and the per-skill degraded paths stand.

Context

D-0003 shipped two native fallbacks for the session-start check, lint_quick.sh and lint_quick.ps1, and said any change to checks 1, 2, 12 (later also 15) must land in both. The smoke test diffs the bash copy against lint_report.py --quick; the PowerShell copy has never run in CI and is "reviewed by hand until a Windows runner exists". No runner exists, and an open thread to test it on a machine with PowerShell has gone unclosed. Each lint change that touched the fallback paid for a copy nobody could verify.

Windows users are not left without a path: Python installs in one command (winget, the Store, python.org), and Git for Windows, which the KB already needs, ships bash, so lint_quick.sh runs there too.

Decision

  1. Template 2.0.0 removes PowerShell support. lint_quick.ps1 is deleted; the PowerShell version comparison in ckb-upgrade Step 2 and every "or the .ps1" mention go with it. Removing a shipped fallback is breaking, hence the major bump. kb_schema_version is unaffected: the content contract stays 1.7.
  2. Scripts stay in Python. Every script the template runs, in skills and in modules, is Python 3.8+ standard library. A module may need other tools (git, Docker, yt-dlp), but the scripts it carries are Python. Two non-Python files stay as named exceptions: lint_quick.sh, the no-Python fallback (it exists because Python is missing), and the mcp module's container entrypoint.sh, which runs inside the image, not on the user's machine.
  3. The 1.x line continues on a 1.x branch, cut from 1.28.1. It gets fixes only, no new features, and is the last line with PowerShell support. It is a release channel like main/test/experimental: a KB tracks it through branch: 1.x in ckb.yaml.
  4. ckb-upgrade never crosses a major version silently. When upstream's major is higher, it quotes the breaking part of the changelog and asks: take the new major, or switch to the maintenance branch. Never from a routine or batch run. This landed in 1.28.1 so that a KB upgrading from 1.28.1 onward already has the guard before it meets 2.0.

Alternatives considered

  • Keep lint_quick.ps1 and add a Windows CI runner. Fixes the verification gap, but keeps the cost of a third implementation for a fallback that only serves people without Python, who can install it in one command.
  • Drop the bash fallback too, making the rule "all scripts are Python" absolute. Considered and declined: bash is tested against the Python reference on every smoke run, so it costs little, and it keeps the session-start check alive on a machine with no Python.
  • No maintenance branch; tell 1.x users to pin a tag. A tag gets no fixes, and ckb-upgrade tracks branches, not tags.

Consequences

  • Windows users without Python lose the native session-start fallback unless they run it under Git Bash; the agent falls through to the manual checklist otherwise.
  • Changes to the quick checks now land in two places (Python, bash), both covered by the smoke test.
  • A KB on 1.28.0 or older upgrading straight from main lacks the major guard; its Step 5 still shows every changed file and the changelog row, and the deleted .ps1 is visible there.
  • Fixes worth having on both lines are made on 1.x and merged forward into main, or cherry-picked when the code has diverged.