docs: make the installer the documented way to deploy the overlay #11

wtclaude · 2026-08-07T21:07:41Z

wtclaude commented

2026-08-07 21:07:41 +00:00

What & why

## Deploy opened with the two deploy.ps1 lines and mentioned the installer only in a trailing note. That ordering was right while the installer was unreleased; it shipped as v0.1.0 on 2026-08-07, so it is now backwards — a shard operator reading top-down lands on a Windows-only script that copies from a git checkout they do not have.

Deploy leads with the installer: one binary syncs this overlay from the release tarball, offers the patch tier, installs the sidecar as a service and prints the values the website needs, with doctor afterwards. The by-hand overlay copy (INSTALL.md Appendix A2) stays as the supported alternative — org lead's call is installer for easy mode, hand deployment still supported including on the dev side.
deploy.ps1 gets its own subsection as the developer path. It deploys from a working tree, which is exactly what the installer cannot do (the installer deploys from a release) — so it keeps a real job while no longer reading as the operator instruction. Also spells out what it does not do: no sidecar, no service, no protocol pairing check.
Layout table marks deploy.ps1 as a developer tool.
"Sidecar & deployment" now says the two halves are deployed together by the installer, rather than describing deploy.ps1 as the mechanism.
CONTRIBUTING: keeps the deploy.ps1 dev loop, adds that changes reach shards through a release — so a change that only works when deploy.ps1 copies it is a change that does not ship. That is a real failure mode: overlay.toml's declared protocol and the per-file manifest are what the installer pairs against, and neither is exercised by a local copy.

No overlay/, patches/ or tools/ changes — documentation only, nothing deployed is touched.

How it was tested

Docs-only. Anchors #deploy, #releases and INSTALL.md's #a2-deploy-the-plugin-overlay verified against their headings.

Companion PRs, same branch name in each repo: docs, installer, link, website.

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)

AI tools were used. Tool(s): Claude Code. 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 `## Deploy` opened with the two `deploy.ps1` lines and mentioned the [installer](https://gitea.whitlocktech.com/RunicGateway/installer) only in a trailing note. That ordering was right while the installer was unreleased; it shipped as v0.1.0 on 2026-08-07, so it is now backwards — a shard operator reading top-down lands on a Windows-only script that copies from a git checkout they do not have. - **Deploy leads with the installer**: one binary syncs this overlay from the release tarball, offers the patch tier, installs the sidecar as a service and prints the values the website needs, with `doctor` afterwards. The by-hand overlay copy (INSTALL.md Appendix A2) stays as the supported alternative — org lead's call is installer for easy mode, hand deployment still supported including on the dev side. - **`deploy.ps1` gets its own subsection as the developer path.** It deploys from a *working tree*, which is exactly what the installer cannot do (the installer deploys from a release) — so it keeps a real job while no longer reading as the operator instruction. Also spells out what it does not do: no sidecar, no service, no protocol pairing check. - **Layout table** marks `deploy.ps1` as a developer tool. - **"Sidecar & deployment"** now says the two halves are deployed together *by the installer*, rather than describing `deploy.ps1` as the mechanism. - **CONTRIBUTING**: keeps the `deploy.ps1` dev loop, adds that changes reach shards through a release — so a change that only works when `deploy.ps1` copies it is a change that does not ship. That is a real failure mode: `overlay.toml`'s declared protocol and the per-file manifest are what the installer pairs against, and neither is exercised by a local copy. No `overlay/`, `patches/` or `tools/` changes — documentation only, nothing deployed is touched. ## How it was tested Docs-only. Anchors `#deploy`, `#releases` and INSTALL.md's `#a2-deploy-the-plugin-overlay` verified against their headings. Companion PRs, same branch name in each repo: docs, installer, link, website. ## 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) - [x] AI tools were used. Tool(s): `Claude Code`. 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-07 21:07:42 +00:00

docs: make the installer the documented way to deploy the overlay 48b16dc70e

"## Deploy" led with deploy.ps1 and mentioned the installer only
afterwards, which is backwards now that the installer is released.

- Deploy leads with the installer, with the by-hand overlay copy
  (INSTALL.md Appendix A2) as the supported alternative.
- deploy.ps1 gets its own subsection as the developer path: it deploys
  from a working tree, which is the one thing the installer cannot do,
  and it installs no sidecar and checks no protocol pairing.
- CONTRIBUTING: note that changes reach shards through a release, so a
  change that only works when deploy.ps1 copies it does not ship.

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

whitlocktech approved these changes 2026-08-07 21:32:09 +00:00

whitlocktech merged commit 0eda2d3a97 into main

2026-08-07 21:32:15 +00:00

whitlocktech deleted branch docs/installer-first-setup

2026-08-07 21:32:16 +00:00

whitlocktech referenced this issue from a commit

2026-08-07 21:32:17 +00:00

Merge pull request 'docs: make the installer the documented way to deploy the overlay' (#11) from docs/installer-first-setup into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/servuo-plugins#11