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

86 lines
4.4 KiB
Markdown

---
type: decision
tldr: 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.
status: accepted
decided_on: 2026-11-11
decided_by: Michał Kopeć
affects: .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
confidence: 0.85
quality: 0.8
last_updated: 2026-11-11
freshness_window_days: 365
retention: 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](0003-python-runtime-with-degraded-fallbacks.md).
> Python as the single scripting runtime, interpreter resolution, the bash
> fallback and the per-skill degraded paths stand.
## Context
[D-0003](0003-python-runtime-with-degraded-fallbacks.md) 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.