- commit
- 48a9e57ab9940e40e6316c9b9c073866fac13d7c
- parent
- f5e685aca851f44389acfa5e89ed6d692b596a49
- author
- Dami <dami.etoile@gmail.com>
- kind
- docs risk score 0.1 of 3, Jev's estimate
| M | README.md | 5 | ++- |
| M | ROADMAP.md | 2 | +- |
| M | docs/ | 58 | ++++++++++++++++++++++++++++-- |
| M | docs/ | 11 | ++++-- |
| M | docs/ | 29 | ++++++++++++++- |
@@ -15,9 +15,12 @@ It is one pure-Go binary.
1515 ## Install1616 1717 ```sh18-go install github.com/FelineStateMachine/012/cmd/012@latest18+curl -fsSL https://f58b.n.zip/install.sh | sh # macOS, Linux: into ~/.local/bin19+go install github.com/FelineStateMachine/012/cmd/012@latest # or build it with Go 1.271920 ```2021 22+On Windows, `irm https://f58b.n.zip/install.ps1 | iex` in PowerShell.23+2124 Then run `012`, or `012 budget.012` to open a sheet. F1 shows every2225 shortcut, F10 or Alt+letter opens the menus, and Ctrl+K searches every2326 command. [Install and run](docs/getting-started/install.md) has the@@ -66,7 +66,6 @@ shared editing in section 3.
6666 | Item | Result | Size |6767 |---|---|---|6868 | A sheet or chart exported as a static HTML page in 012's look | Sharing a sheet with someone without 012 | S |69-| Release archives and an install script served from the owner's nzip server | Installing without Go | S |7069 7170 ### 6. Agents7271 @@ -165,6 +164,7 @@ stream above rather than a design of their own.
165164 166165 - `make check` before every push; demo tapes (`make demos`); annotated version tags with release notes (v0.2.0 onward; v0.1.0 remains on the Go module proxy): [Testing](docs/contributing/testing.md)167166 - A release checklist (XLSX output opened in Excel, LibreOffice and Google Sheets) and `make dist`, release archives cross-compiled locally with SHA256SUMS: [Releasing](docs/contributing/releasing.md)167+- Installing without Go: `curl -fsSL https://f58b.n.zip/install.sh | sh` (and `install.ps1` on Windows) with the release archives served from the docs site by `make site-release`: [Install and run](docs/getting-started/install.md), [Releasing](docs/contributing/releasing.md#publishing)168168 - `make stress-report` flags regressions against the last release's run, allowing for noise: [Observability](docs/contributing/observability.md#regressions-against-the-last-release)169169 - Grafana: recent traces and a trace view of the nested spans: [Observability](docs/contributing/observability.md#the-stack)170170 - Every overlay, prompts and formula suggestions behind narrow hosts, most in packages of their own with fake-host tests: [Architecture](docs/contributing/architecture.md#the-ui)@@ -7,8 +7,9 @@ sidebar_position: 8
77 88 A release is an annotated version tag whose message is the release99 notes, and archives of the binaries built from it on a maintainer's10-machine. The GitHub repository only hosts the code: nothing builds or11-publishes there, and `make dist` uploads nothing.10+machine, served with the docs site on the owner's nzip server along11+with the install scripts that download them. The GitHub repository only12+hosts the code: nothing builds or publishes there.1213 1314 ## Checklist1415 @@ -26,6 +27,9 @@ flowchart TD
2627 tag -->|the module proxy| install[go install ...@v1.2.3]2728 tag --> dist[make dist]2829 dist --> archives[dist/: archives, SHA256SUMS]30+ archives --> site[make site-release]31+ site --> push[nzip site push website/build public:012]32+ push --> live[install.sh, /releases/v1.2.3/ and /releases/latest/ live]2933 ```3034 3135 1. **`make check`** passes on the commit to be tagged (see@@ -56,6 +60,18 @@ flowchart TD
5660 The Go module proxy picks the tag up, so `go install5761 github.com/FelineStateMachine/012/cmd/012@v1.2.3` works from then on.5862 6. **Binaries**: `make dist VERSION=v1.2.3` on the tagged commit.63+7. **Publish** the site with the release64+ ([Publishing](#publishing)):65+66+ ```sh67+ SITE_URL=https://f58b.n.zip make site-release VERSION=v1.2.368+ nzip site push website/build public:01269+ ```70+71+ then check the live copy: `SHA256SUMS` at72+ `https://f58b.n.zip/releases/v1.2.3/` matches `dist/SHA256SUMS`, and73+ `curl -fsSL https://f58b.n.zip/install.sh | PREFIX=$(mktemp -d) sh`74+ installs a `012` whose `012 version` prints v1.2.3.5975 6076 ## File fixtures6177 @@ -106,4 +122,40 @@ dist/SHA256SUMS
106122 refuses a version that isn't `vMAJOR.MINOR.PATCH` (with an optional107123 `-suffix`) or that is tagged at another commit than the one checked108124 out, and warns when the tree has uncommitted changes. The archives and109-`SHA256SUMS` are what a release attaches, wherever it is published.125+`SHA256SUMS` are what a release publishes.126+127+## Publishing128+129+`make site-release` (`scripts/site-release.sh`) builds the docs site as130+`make site` does and adds the release to `website/build`:131+132+```133+website/build/install.sh134+website/build/install.ps1135+website/build/releases/v1.2.3/ archives, SHA256SUMS, an index page136+website/build/releases/latest/ the same files137+```138+139+`VERSION` defaults to the newest version tag. The archives are `dist/`'s140+when its `SHA256SUMS` names that version; otherwise the script checks141+the tag out in a temporary git worktree, runs `make dist` there and142+keeps the result in `dist/`, so the site can be published from a commit143+after the tag. It checks the archives against `SHA256SUMS` before144+copying them. `SITE_URL` also goes into the copied install scripts, so a145+site built for another address serves scripts that download from it.146+147+The site serves one release, `VERSION`, under both addresses; earlier148+releases stay installable with `go install ...@v1.2.3`. Every push149+replaces the whole site, so the docs are always published with150+`make site-release` ([The docs site](site.md#where-it-lives)): a push151+of a plain `make site` build leaves the install script without its152+archives.153+154+The install scripts live in `scripts/install/`. `install.sh` is POSIX155+sh (it runs under dash as well as sh) and needs curl or wget, tar, and156+sha256sum, shasum or openssl. `install_test.go`, in `make test`, runs157+it as a file and piped to the shell against a local server holding a158+fake release: the latest into `~/.local/bin`, a version under `PREFIX`,159+and a refusal of an archive whose checksum doesn't match. `install.ps1`160+has no automated test, as no PowerShell is assumed on a maintainer's161+machine; try it on Windows when it changes.@@ -26,14 +26,19 @@ site`); the site sits at the root of its host.
2626 ## Where it lives2727 2828 The site is published at [f58b.n.zip](https://f58b.n.zip/), a public,29-permanent address on the owner's nzip server. To publish a new build to30-the same address:29+permanent address on the owner's nzip server, which also serves the30+install scripts and the latest release's archives. To publish a new31+build to the same address:3132 3233 ```sh33-SITE_URL=https://f58b.n.zip make site34+SITE_URL=https://f58b.n.zip make site-release3435 nzip site push website/build public:0123536 ```3637 38+`make site-release` is `make site` with the release added39+([Publishing](releasing.md#publishing)); a push of a plain `make site`40+build would take the install script and the archives off the site.41+3742 The target keeps its policies (public, no expiry) between pushes.3843 3944 ## The build is a docs check@@ -5,12 +5,37 @@ sidebar_position: 2
55 66 # Install and run77 8+012 is one binary. On macOS or Linux, the install script puts the latest9+release in `~/.local/bin`:10+11+```sh12+curl -fsSL https://f58b.n.zip/install.sh | sh13+```14+15+It picks the archive for your OS and architecture, checks it against the16+release's `SHA256SUMS` and says where it put `012`. `PREFIX=/opt/012`17+installs into `/opt/012/bin` instead, and `sh -s -- --system` into18+`/usr/local/bin`, running `sudo` (and printing the command first) only19+when that directory isn't writable; `sh -s -- --version v0.3.0` picks a20+release. On Windows, in PowerShell:21+22+```powershell23+irm https://f58b.n.zip/install.ps1 | iex24+```25+26+which installs `012.exe` into `%LOCALAPPDATA%\Programs\012\bin` and adds27+that folder to your PATH, without administrator rights. The archives and28+`SHA256SUMS` are also at29+[f58b.n.zip/releases/latest/](https://f58b.n.zip/releases/latest/) to30+download by hand.31+32+With Go 1.27 or later, build it from source instead:33+834 ```sh935 go install github.com/FelineStateMachine/012/cmd/012@latest1036 ```1137 12-012 needs Go 1.27 to build and is one pure-Go binary. From a clone,13-`make build` puts it in `bin/012`.38+From a clone, `make build` puts it in `bin/012`.1439 1540 ```sh1641 012 # a new sheet