diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index babdb30..1134ff7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,8 +77,8 @@ use `smoke` for the base image. Assertions write machine-readable Evidence when Evidence rather than inferring a pass from job status. Changes to persistence, setup, ownership, Compose, Dev Containers, Windows, or -Podman must update the automated scenarios where possible and the remaining -manual matrix in `uat-checklist.md`. +Podman must update the automated scenarios where possible. Optional follow-up +checks live in `uat-checklist.md`; they are not an implied release gate. ## Project structure @@ -156,8 +156,8 @@ creates a non-discoverable draft GitHub Release, and verifies the downloaded draft before publication can run. There is no release rebuild. Prerelease tags publish automatically after those automated gates. For a stable -release, create the immutable final-version tag before physical qualification, -test the prepared digest and draft assets, then approve the separate +release, create the immutable final-version tag, verify the prepared digest and +draft assets, then approve the separate `publish-release` job. Repository administrators must configure `stable-release` with a required human reviewer and leave `prerelease-auto` unprotected. Approval publishes the exact prepared bytes; @@ -186,7 +186,8 @@ published immutable reruns must verify metadata without editing it. ## Pull requests and issues Keep commits outcome-oriented and explain why the change is needed. Include -tests, Evidence IDs, supported migration behavior, and any remaining manual UAT. +tests, Evidence IDs, supported migration behavior, and any explicitly requested +optional UAT. GitHub Issues is the tracker. A ready implementation issue contains reproduction or design evidence, acceptance criteria, dependencies, and the relevant triage diff --git a/ROADMAP.md b/ROADMAP.md index 8f73472..9a1fdd5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,22 +1,21 @@ # Roadmap -## v1.1.0 release gate +## v1.2.1 release gate - Pass every assertion in `scripts/e2e-required.tsv` against one immutable Candidate digest. -- Complete the real-host matrix in `uat-checklist.md`, especially Windows, - macOS, Fedora rootless Podman/SELinux, Dev Containers/Codespaces, and - physical arm64 (tracked by GitHub issues #99–#105). -- `v1.1.0-rc5` completed the automatic publication rehearsal. +- Keep platform-specific manual qualification optional; automated Candidate + Evidence is the release gate. +- `v1.2.1-rc5` completed the automatic publication rehearsal. - Keep GitHub immutable Releases enabled, keep the no-bypass `v*` update and deletion ruleset active, and verify the stable/prerelease environment protections before creating a final tag. -- Create the immutable `v1.1.0` tag so CI builds one final Candidate and - prepares its signed assets as a non-discoverable draft. Complete physical - qualification against that exact digest and draft asset set, then approve - the `v1.1-production` environment to publish those bytes without rebuilding. +- Create the immutable `v1.2.1` tag so CI builds one final Candidate and + prepares its signed assets as a non-discoverable draft, then approve the + protected stable environment to publish those bytes without rebuilding. Do not retarget the final tag if qualification fails; fix forward with a new version. -- Resolve or explicitly defer every open release-blocking GitHub issue. +- Verify the final Candidate identity, attestation, aliases, and non-rewind + behavior in issue #131. ## After v1.1 @@ -38,5 +37,5 @@ tmux, and Zellij with clear overrides for bat/delta themes. - **Assistant completion notifications** — opt-in terminal bell/desktop adapter around long-running assistant commands. -- **Native platform depth** — move remaining Windows, macOS, Podman/SELinux, - and physical-arm64 UAT into automated adapters where runners permit. +- **Native platform depth** — improve platform adapters when concrete defects + justify the work; do not maintain a standing manual qualification matrix. diff --git a/uat-checklist.md b/uat-checklist.md index c38471d..7d557f4 100644 --- a/uat-checklist.md +++ b/uat-checklist.md @@ -1,24 +1,21 @@ -# Squarebox v1.2 manual UAT +# Squarebox v1.2.1 release checks Automated release assertions are defined in `scripts/e2e-required.tsv` and -reported from exact Evidence by `.github/workflows/e2e.yml`. This checklist -contains only behavior that still needs a person, real host integration, or -hardware outside GitHub-hosted runners. An unchecked item is **untested**, not -an automated pass. +reported from exact Evidence by `.github/workflows/e2e.yml`. That automated +Candidate workflow is the v1.2.1 release gate. A per-platform manual +qualification matrix is not required for this release. -Record the Candidate version, source SHA, image digest, host OS, architecture, -container runtime/version, and result for every run. +Native PowerShell remains a separate adapter and does not claim `SSH_AUTH_SOCK` forwarding; +adapter boundaries are covered by automated/static checks. + +Record the Candidate version, source SHA, image digest, and result for any +optional follow-up run. Release tracker: [v1.2.1 #125](https://github.com/SquareWaveSystems/squarebox/issues/125). -Qualification issues: [Linux desktop #126](https://github.com/SquareWaveSystems/squarebox/issues/126), -[Fedora/Podman #127](https://github.com/SquareWaveSystems/squarebox/issues/127), -[macOS #128](https://github.com/SquareWaveSystems/squarebox/issues/128), -[Windows/Git Bash #129](https://github.com/SquareWaveSystems/squarebox/issues/129), -[Dev Containers/Codespaces #130](https://github.com/SquareWaveSystems/squarebox/issues/130), -[demo regeneration #104](https://github.com/SquareWaveSystems/squarebox/issues/104), and -[physical Candidate qualification #131](https://github.com/SquareWaveSystems/squarebox/issues/131). +Optional primary-Linux follow-up: [#126](https://github.com/SquareWaveSystems/squarebox/issues/126). +Final Candidate and publication: [#131](https://github.com/SquareWaveSystems/squarebox/issues/131). -## Linux desktop — Docker +## Optional primary-Linux follow-up - [ ] Fresh Bash installer: launch, interactive setup, exit, resume, rebuild, uninstall - [ ] Existing v1.1 Managed home upgrade: no repeated prompts; Selections reconcile @@ -29,77 +26,12 @@ Qualification issues: [Linux desktop #126](https://github.com/SquareWaveSystems/ - [ ] Purge refuses an unrelated directory/container/image/volume with a colliding name - [ ] Docker daemon unavailable during uninstall produces a clear nonzero partial-cleanup result -## Rootless Podman and SELinux - -- [ ] Fedora with enforcing SELinux: Workspace/SSH/system labels remain unchanged and the documented `label=disable` tradeoff is acceptable -- [ ] Rootless keep-id mapping: host and Box create mutually writable files -- [ ] Rootless Podman rejects PUID/PGID values that differ from the invoking host identity -- [ ] Stop/start, replacement, rebuild, and purge honor the same Install identity -- [ ] SSH agent and read-only SSH fallback both work - -## macOS — Docker Desktop - -- [ ] Fresh install and upgrade with paths containing spaces -- [ ] SSH agent forwarding works; fallback private-key mount remains read-only -- [ ] Missing `/etc/localtime` uses the documented timezone fallback -- [ ] Rebuild and purge preserve/remove only recorded Managed resources - -## Windows — native PowerShell 7 and Docker Desktop - -- [ ] Fresh `install.ps1`, Box launch, PowerShell rebuild, and `uninstall.ps1` remain on the same native adapter -- [ ] Shell functions work in ConsoleHost and VS Code PowerShell hosts -- [ ] Install from one PowerShell host and uninstall from another removes the intended integration -- [ ] Git identity contains only name/email; host credential/signing configuration is not mounted -- [ ] Native PowerShell mounts `%USERPROFILE%\.ssh` read-only and does not claim `SSH_AUTH_SOCK` forwarding -- [ ] Paths containing spaces and non-ASCII characters survive every lifecycle action -- [ ] Install identity access is limited by the current user's Windows install-directory ACL -- [ ] Native PowerShell rejects a Git Bash-created Install identity without modifying its resources or profiles - -## Git Bash compatibility - -- [ ] Bash integration uses the MSYS home while the Install identity uses the Windows user home -- [ ] SSH agent socket translation works with Docker Desktop path conversion disabled -- [ ] Git Bash install, rebuild, and uninstall consume the Bash-created identity only -- [ ] Git Bash rejects a native PowerShell-created Install identity without modifying its resources or shell integration - -## Interactive setup - -- [ ] Cancel each multi-select and confirm the prior Selection is preserved -- [ ] Deliberately choose an empty Selection and confirm it is saved distinctly from cancel -- [ ] Fail one assistant install and confirm aliases target the first successfully observed assistant -- [ ] GitHub device authentication succeeds; decline marker and credentials survive Box replacement -- [ ] Claude, Copilot, Gemini, Codex, OpenCode, Pi, and Oh My Pi launch after installation -- [ ] Copilot uses the supported `copilot` command -- [ ] Bash initializes Starship, Zoxide, fzf keybindings/completion, aliases, and mise shims -- [ ] Zsh and Fish initialize Starship, Zoxide, the `fzf`/`ff` command path, aliases, and mise shims -- [ ] Section-only AI/editor/TUI reruns refresh Fish derived configuration -- [ ] A non-first default editor survives Box replacement and noninteractive reconciliation -- [ ] Explicit `set -g mouse off` remains respected during tmux migration -- [ ] Herdr launches after installation and survives Box replacement from the Managed home - -## Interactive tools - -- [ ] `lazygit`, `yazi`, `elio`, `gh-dash`, and Helix (`hx`) render and accept input -- [ ] `gum` and `fzf` interactive modes work with the host terminal -- [ ] tmux and Zellij keybindings match the documentation -- [ ] Neovim/LazyVim first launch completes without wedging dpkg under the timezone mount - -## Dev Containers and Codespaces - -- [ ] VS Code Dev Containers builds the tagged Candidate source, runs `postCreateCommand`, and reopens successfully (source rebuild is not byte-identical to the published image) -- [ ] `gh codespace ssh` attaches to a Codespace built from the custom Squarebox image -- [ ] GitHub Codespaces runs the noninteractive defaults and preserves independent successful Selections after one section fails -- [ ] Custom `SQUAREBOX_DC_MULTIPLEXERS` defaults are observed; an explicit empty value opts out; and an existing multiplexer Selection takes precedence on rebuild -- [ ] Rebuilds preserve Workspace Selection state and Managed-home authentication/toolchains - ## Candidate promotion -- [ ] Pull the published Candidate by digest on real amd64 hardware -- [ ] Pull the same Candidate digest on real arm64 hardware - [ ] Verify the version file, MOTD, Git source ref, and `release.json` agree - [ ] Confirm the active release-tag ruleset rejects update/deletion of the `v*` tag and that its peeled remote commit still equals the Candidate source SHA - [ ] Download the non-discoverable draft assets with authenticated `gh release download` and verify their hashes and Cosign identity signature -- [ ] Run fresh and upgraded Compose flows against the digest +- [ ] Run the automated Candidate suite and confirm all required Evidence passes - [ ] Confirm stable installers cannot discover the Release until all gates pass - [ ] Record the qualification evidence and explicit promote/no-promote decision in [issue #131](https://github.com/SquareWaveSystems/squarebox/issues/131) - [ ] Approve the waiting `stable-release` environment deployment to publish the tested Candidate without rebuilding different image bytes