docs(installer): put Phase 5 before the cutover, and flag Windows SCM as untested #95

wtclaude · 2026-08-05T10:01:15Z

wtclaude commented

2026-08-05 10:01:15 +00:00

What & why

Two decisions from the org lead, recorded in the design of record.

Phase 5 runs before the `edge → main` cutover

The original order assumed the cutover would cut a v1 and packaging would follow as a v1.x. But Phase 5 changes the release layout itself (§3 — .deb, MSI, arm64), so shipping first would mean a first release that is immediately superseded, and operators who downloaded a bare binary being told to re-download a package instead. Deferring costs nothing: nothing is published from edge, and INSTALL.md's Appendix A is the supported path meanwhile.

The cutover now has two stated entry criteria

Phase 5, packaging polish.
The Windows SCM half verified on a real host.

The second is called out explicitly rather than left as a footnote. sc create, the virtual service account, the failure actions and the token-file ACL have still never been executed anywhere — and running the systemd half for real is exactly what turned up a bug no unit test had (the user_created flag, installer#8). Nothing should be released while the only untested code in the crate is the half that registers a service.

Windows containers are not a shortcut for this, for the record: the Containers and Hyper-V features are disabled on the dev machine, so enabling them needs elevation plus a reboot — strictly more intrusive than running the check script in an elevated shell.

How it was tested

Prose only. Both statements are decisions rather than observations, and are attributed and dated in the text.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Two decisions from the org lead, recorded in the design of record. ### Phase 5 runs *before* the `edge → main` cutover The original order assumed the cutover would cut a v1 and packaging would follow as a v1.x. But Phase 5 changes the **release layout itself** (§3 — `.deb`, MSI, arm64), so shipping first would mean a first release that is immediately superseded, and operators who downloaded a bare binary being told to re-download a package instead. Deferring costs nothing: nothing is published from `edge`, and `INSTALL.md`'s Appendix A is the supported path meanwhile. ### The cutover now has two stated entry criteria 1. Phase 5, packaging polish. 2. **The Windows SCM half verified on a real host.** The second is called out explicitly rather than left as a footnote. `sc create`, the virtual service account, the failure actions and the token-file ACL have **still never been executed anywhere** — and running the *systemd* half for real is exactly what turned up a bug no unit test had (the `user_created` flag, installer#8). Nothing should be released while the only untested code in the crate is the half that registers a service. Windows containers are not a shortcut for this, for the record: the `Containers` and `Hyper-V` features are disabled on the dev machine, so enabling them needs elevation *plus* a reboot — strictly more intrusive than running the check script in an elevated shell. ## How it was tested Prose only. Both statements are decisions rather than observations, and are attributed and dated in the text. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-08-05 10:01:16 +00:00

docs(installer): put Phase 5 before the cutover, and flag Windows SCM as untested 3a6b9196fa

Two decisions from the org lead, recorded in the design of record.

Phase 5 (packaging polish) now runs BEFORE the edge -> main cutover
rather than after it. The original order assumed the cutover would cut a
v1 and packaging would follow as a v1.x, but this phase changes the
release layout itself: shipping first would mean a first release that is
immediately superseded, and operators who downloaded a bare binary being
told to re-download a package. Deferring costs nothing — nothing is
published from `edge`, and INSTALL.md's Appendix A is the supported path
meanwhile.

The cutover therefore has two entry criteria, stated in the status
header and at Phase 5: packaging polish, and the Windows SCM half being
verified on a real host. The second is called out explicitly because
`sc create`, the virtual service account, the failure actions and the
token-file ACL have still never been executed anywhere — and running the
systemd half for real is precisely what turned up a bug no unit test
had. Nothing should be released while the only untested code is the half
that registers a service.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech merged commit 3eb9fa8653 into main

2026-08-05 10:12:20 +00:00

whitlocktech deleted branch docs/installer-polish-before-cutover

2026-08-05 10:12:20 +00:00

whitlocktech referenced this issue from a commit

2026-08-05 10:12:21 +00:00

Merge pull request 'docs(installer): put Phase 5 before the cutover, and flag Windows SCM as untested' (#95) from docs/installer-polish-before-cutover into main

wtclaude referenced this pull request

2026-08-05 10:21:08 +00:00

docs(installer): Phase 5 — scope, the §5.3 correction, and the operator guide #96

Sign in to join this conversation.