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>
86 lines
4.4 KiB
Markdown
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.
|