From 85b744a69756a0a2e54cb7d50d0140f18ec003a4 Mon Sep 17 00:00:00 2001 From: Damir Vazgird Date: Tue, 6 Oct 2026 16:05:44 -0700 Subject: [PATCH] docs: record the v0.1.11 publication, the first crates.io release (P3-39) Install docs lead with crates.io; P3-39 done; dogfood-log release row and P3-08 list. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 14 ++++++++++---- SECURITY.md | 2 +- wiki/guides/configuration.md | 2 +- wiki/guides/development.md | 9 ++++++--- wiki/guides/releasing.md | 5 ++++- wiki/roadmap/dogfood-log.md | 1 + wiki/roadmap/phase-3-alpha.md | 4 ++-- 7 files changed, 25 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 8278425..c742260 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,13 @@ Phase 2 is done (closed 2026-10-06). Phase 3 alpha polish is shipped through v0. ## Install -From git (supported today): +From [crates.io](https://crates.io/crates/wiki-reader-tui): + +```bash +cargo install --locked wiki-reader-tui +``` + +Or the latest `main` from git: ```bash cargo install --locked --git https://github.com/luckgrid/wiki-reader wiki-reader-tui @@ -59,7 +65,7 @@ cargo install --locked --git https://github.com/luckgrid/wiki-reader wiki-reader Lite build (no images, SVG or Mermaid pictures; diagrams stay text, source or a placeholder; smaller binary, faster build; see [ADR-0023](wiki/decisions/0023-lite-build-is-a-cargo-feature.md)). It is a cargo feature only; there is no `-lite` release download: ```bash -cargo install --locked --no-default-features --git https://github.com/luckgrid/wiki-reader wiki-reader-tui +cargo install --locked --no-default-features wiki-reader-tui ``` The package is named `wiki-reader-tui` (the command it installs is still `wiki-reader`), because the name `wiki-reader` is taken on crates.io. Releases up to and including v0.1.10 use the old package name: pin one with `cargo install --locked --git https://github.com/luckgrid/wiki-reader --tag v0.1.10 wiki-reader`. If you installed `wiki-reader` before the rename, run `cargo uninstall wiki-reader` first (or add `--force`), because cargo will not let a second package overwrite the same command. @@ -73,7 +79,7 @@ tar xf wiki-reader-vX.Y.Z-.tar.gz Binaries are unsigned and not notarized. Browser downloads on macOS may be quarantined; clear with `xattr -d com.apple.quarantine path/to/wiki-reader` if Gatekeeper blocks them (`curl` downloads usually skip quarantine). The Linux binary is built on `ubuntu-latest` and links that runner's glibc, so older distros may need to build from source or use `cargo install`. -crates.io packaging metadata is prepared (`version` on path deps, repository/readme); the crates are not published yet. +The crates are published on crates.io: [`wiki-reader-tui`](https://crates.io/crates/wiki-reader-tui) (the binary) with the library crates `wiki-reader-core`, `wiki-reader-media` and `wiki-reader-render`. ## Upgrade @@ -81,7 +87,7 @@ Check your version with `wiki-reader --version` and `which wiki-reader`. Upgrade ```bash # cargo install → ~/.cargo/bin (--force replaces it; a --tag before the rename needs the old name, see Install) -cargo install --locked --force --git https://github.com/luckgrid/wiki-reader wiki-reader-tui +cargo install --locked --force wiki-reader-tui # release tarball → usually ~/.local/bin (verify and unpack as above, then overwrite) install -m 0755 wiki-reader-vX.Y.Z-/wiki-reader ~/.local/bin/wiki-reader diff --git a/SECURITY.md b/SECURITY.md index 09f458e..d79bb38 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,7 @@ ## Supported versions -Security fixes land on the latest release (GitHub Releases, and crates.io once published). wiki-reader is pre-1.0 (`0.x`): only the latest release is supported, and fixes are not backported to older ones. +Security fixes land on the latest release (crates.io and GitHub Releases). wiki-reader is pre-1.0 (`0.x`): only the latest release is supported, and fixes are not backported to older ones. ## Reporting a vulnerability diff --git a/wiki/guides/configuration.md b/wiki/guides/configuration.md index 395059e..d595d82 100644 --- a/wiki/guides/configuration.md +++ b/wiki/guides/configuration.md @@ -64,7 +64,7 @@ Legacy `nav.labels = "title+filename"` is read as `"title"` with one warning per ## Lite build -`cargo install --locked --no-default-features --git https://github.com/luckgrid/wiki-reader wiki-reader` builds without the image stack ([ADR-0023](../decisions/0023-lite-build-is-a-cargo-feature.md)). `images.enabled` and `images.max_slot_rows` are still read but have no effect: every image is a text placeholder, no graphics probe runs, and the options window hides the Images and Max image rows groups. `diagrams = "image"` renders the text tier with the header `lite build: no image tier`; `auto` and `text` look the same as on a terminal without graphics. Everything else is unchanged. +`cargo install --locked --no-default-features wiki-reader-tui` builds without the image stack ([ADR-0023](../decisions/0023-lite-build-is-a-cargo-feature.md)). `images.enabled` and `images.max_slot_rows` are still read but have no effect: every image is a text placeholder, no graphics probe runs, and the options window hides the Images and Max image rows groups. `diagrams = "image"` renders the text tier with the header `lite build: no image tier`; `auto` and `text` look the same as on a terminal without graphics. Everything else is unchanged. ## Options window diff --git a/wiki/guides/development.md b/wiki/guides/development.md index f8a18ed..bbf5953 100644 --- a/wiki/guides/development.md +++ b/wiki/guides/development.md @@ -23,11 +23,14 @@ How to pick up work in this repo. Supported path today — install the binary from git: ```bash -# Full build (default features: images / Mermaid raster) -cargo install --locked --git https://github.com/luckgrid/wiki-reader wiki-reader-tui +# Full build from crates.io (default features: images / Mermaid raster) +cargo install --locked wiki-reader-tui # Lite build (no image stack; ADR-0023) -cargo install --locked --no-default-features --git https://github.com/luckgrid/wiki-reader wiki-reader-tui +cargo install --locked --no-default-features wiki-reader-tui + +# Latest main instead of the last release +cargo install --locked --git https://github.com/luckgrid/wiki-reader wiki-reader-tui ``` Tagged releases attach platform tarballs (macOS arm64 / x86_64, Linux x86_64) plus SHA256 checksums. To upgrade, replace or roll back an installed version, see [Releasing and upgrading](releasing.md), which also covers how maintainers cut, dry-run, verify and fix a release. The tag name must be `v` plus the workspace `Cargo.toml` version (for example `v0.1.N`). diff --git a/wiki/guides/releasing.md b/wiki/guides/releasing.md index 4456ce8..798a581 100644 --- a/wiki/guides/releasing.md +++ b/wiki/guides/releasing.md @@ -36,10 +36,13 @@ Quit any running wiki-reader before replacing the binary. ### Installed with cargo ```bash +# Latest release on crates.io (also how you roll back: add --version 0.1.N) +cargo install --locked --force wiki-reader-tui + # Latest main cargo install --locked --force --git https://github.com/luckgrid/wiki-reader wiki-reader-tui -# A specific release (also how you roll back); tags up to v0.1.10 use the old package name +# A specific release from git; tags up to v0.1.10 use the old package name cargo install --locked --force --git https://github.com/luckgrid/wiki-reader --tag v0.1.N wiki-reader-tui cargo install --locked --force --git https://github.com/luckgrid/wiki-reader --tag v0.1.10 wiki-reader ``` diff --git a/wiki/roadmap/dogfood-log.md b/wiki/roadmap/dogfood-log.md index b71c8b0..f702537 100644 --- a/wiki/roadmap/dogfood-log.md +++ b/wiki/roadmap/dogfood-log.md @@ -242,6 +242,7 @@ Phase 2 was closed early on 2026-10-06 (clock started 2026-09-29), so dogfooding | Date | Kind | Note | Task IDs | |------|------|------|----------| | 2026-10-06 | decision | Prepare v0.1.11, the first release published to crates.io (package `wiki-reader-tui`; `wiki-reader-core`, `-media` and `-render` alongside). Content since v0.1.10: the crates.io prep (rename, MSRV 1.92, `cargo-deny`, licences and notices, SECURITY.md), the Rust `check-orphan-exit` and its unread-master case, one `wiki/assets/` directory, the viewer screenshots, dependency bumps (`signal-hook` 0.4, `toml` 1.x, `mermaid-text` 0.57, `insta`, actions). The release workflow no longer flags `v0.1.*` tags as prereleases, and `link-check` bans the word in current docs. Phase 2 and Phase 3 are closed, so the release waits on nothing else; each publish command is confirmed with the operator | P3-39, P3-40, P3-41 | +| 2026-10-06 | release | [v0.1.11](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.11) published, the first release on crates.io (`wiki-reader-tui` with `wiki-reader-core`, `-media` and `-render`) and the first GitHub release not flagged as a prerelease. Merge commit `7532065` had green CI; the Release workflow dry run built all three targets before the tag. `cargo publish --workspace --locked` published four crates; tag `v0.1.11` produced three tarballs with checksums. Verified: `cargo install --locked wiki-reader-tui` and `--no-default-features` in fresh `CARGO_HOME`s report 0.1.11 (17.6 MB and 9.0 MB), the macOS arm64 download matches its checksum and carries the notice files, docs.rs built `wiki-reader-core`. Install docs now lead with crates.io | P3-39 | ## Related diff --git a/wiki/roadmap/phase-3-alpha.md b/wiki/roadmap/phase-3-alpha.md index 59dc120..9f6d357 100644 --- a/wiki/roadmap/phase-3-alpha.md +++ b/wiki/roadmap/phase-3-alpha.md @@ -86,7 +86,7 @@ Per batch: manual passes in Ghostty and herdr, plus iTerm2/tmux for media or fal | ID | Task | Reqs | Status | Notes | |----|------|------|--------|-------| -| P3-08 | Install via `cargo install` + release binaries | | done | daf8fc5; hygiene f90c378; release hardening 9012fce; [v0.1.0-alpha.1](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.1); [v0.1.0-alpha.2](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.2); [v0.1.0-alpha.3](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.3); [v0.1.0-alpha.4](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.4); [v0.1.0-alpha.4.1](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.4.1); [v0.1.0-alpha.5](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.5) (P3-12c/d Mermaid image tier); [v0.1.0-alpha.5.1](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.5.1) (P2-55 copy path); [v0.1.1](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.1) (P3-07/11/13/14/15, the first `v0.1.N` tag); [v0.1.2](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.2) (2026-10-03, P2-56 theme-switch fix and docs filing; three release targets and macOS arm64 download verified); [v0.1.3](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.3) (2026-10-03, P2-59 narrow-nav fix and the Batch A chrome pass P3-16/17/18; three release targets and macOS arm64 download verified); [v0.1.4](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.4) (2026-10-03, P2-60 diagram upload fix, the herdr launcher P3-09 and page publishing P3-10; three release targets and macOS arm64 download verified); [v0.1.5](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.5) (2026-10-04, the lite build P3-19, viewers P3-20/21/22, screenshots P3-23, code viewer P3-24, toolbar icons P3-25 and status enum P3-26; three release targets, macOS arm64 download and the lite install from the tag verified); [v0.1.6](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.6) (2026-10-04, the audit fixes P3-27 crashes and terminal safety and P3-28 performance; three release targets, macOS arm64 download and the lite install from the tag verified); [v0.1.7](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.7) (2026-10-05, P3-29 robustness); [v0.1.8](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.8) (2026-10-05, P3-30 table-viewer expand); [v0.1.9](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.9) (2026-10-05, P3-31/P3-31b baseline and P3-34 linear wrap); [v0.1.10](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.10) (2026-10-06, P3-37 orphaned-reader exit: session-leader watchdog, hung-up terminal exit, no panic on a dead stderr, `WIKI_READER_NO_WATCHDOG`; three release targets, macOS arm64 download and the lite install from the tag verified) | +| P3-08 | Install via `cargo install` + release binaries | | done | daf8fc5; hygiene f90c378; release hardening 9012fce; [v0.1.0-alpha.1](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.1); [v0.1.0-alpha.2](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.2); [v0.1.0-alpha.3](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.3); [v0.1.0-alpha.4](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.4); [v0.1.0-alpha.4.1](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.4.1); [v0.1.0-alpha.5](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.5) (P3-12c/d Mermaid image tier); [v0.1.0-alpha.5.1](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.0-alpha.5.1) (P2-55 copy path); [v0.1.1](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.1) (P3-07/11/13/14/15, the first `v0.1.N` tag); [v0.1.2](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.2) (2026-10-03, P2-56 theme-switch fix and docs filing; three release targets and macOS arm64 download verified); [v0.1.3](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.3) (2026-10-03, P2-59 narrow-nav fix and the Batch A chrome pass P3-16/17/18; three release targets and macOS arm64 download verified); [v0.1.4](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.4) (2026-10-03, P2-60 diagram upload fix, the herdr launcher P3-09 and page publishing P3-10; three release targets and macOS arm64 download verified); [v0.1.5](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.5) (2026-10-04, the lite build P3-19, viewers P3-20/21/22, screenshots P3-23, code viewer P3-24, toolbar icons P3-25 and status enum P3-26; three release targets, macOS arm64 download and the lite install from the tag verified); [v0.1.6](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.6) (2026-10-04, the audit fixes P3-27 crashes and terminal safety and P3-28 performance; three release targets, macOS arm64 download and the lite install from the tag verified); [v0.1.7](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.7) (2026-10-05, P3-29 robustness); [v0.1.8](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.8) (2026-10-05, P3-30 table-viewer expand); [v0.1.9](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.9) (2026-10-05, P3-31/P3-31b baseline and P3-34 linear wrap); [v0.1.10](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.10) (2026-10-06, P3-37 orphaned-reader exit: session-leader watchdog, hung-up terminal exit, no panic on a dead stderr, `WIKI_READER_NO_WATCHDOG`; three release targets, macOS arm64 download and the lite install from the tag verified); [v0.1.11](https://github.com/luckgrid/wiki-reader/releases/tag/v0.1.11) (2026-10-06, first crates.io release (P3-39), Rust orphan-exit check (P3-41), one assets directory (P3-40); three release targets, macOS arm64 download and both registry installs verified) | | P3-06 | Help overlay with clickable keys | | done | done via P2-20 (#71) | | P3-07 | Themes | | done | Reworked 2026-10-02 (local time; [ADR-0019](../decisions/0019-theme-presets.md) retains its immutable UTC date, 2026-10-03): `dark` / `light` take the luckgrid.net palette, `herdr` follows the theme named in herdr's config and is the default inside herdr; live follow is P4-05. Original: `theme = dark \| light \| herdr` wired to `Theme::from_name`; light preset with a contrast test; syntect theme and Mermaid palette follow the preset (diagrams were always drawn light before); herdr preset is vesper-based; quadrant/xy-chart/ER-key fills stay light (renderer hard-codes them). Checked 2026-10-02: Mermaid fixtures look right in the default (dark) theme. Light and herdr presets got their in-app visual pass with the options window (P3-13) | | P3-11 | Layout and theme config | C1 | done | `nav.position = left \| right` (default left); divider on the inner edge; Viewer ←/→ at the edge toward the nav hands focus over. Nav width stays session-only (P2-14). No other layout keys (formatted view removed, [ADR-0014](../decisions/0014-remove-formatted-view-toggle.md)). Feature request from 2026-09-30 dogfood | @@ -128,7 +128,7 @@ Per batch: manual passes in Ghostty and herdr, plus iTerm2/tmux for media or fal | P3-36 | Audit fixes: process and tooling | — | deferred | [audit-v0.1.8.md](audit-v0.1.8.md). V17 remainder (reap children, herdr timeout, surface open errors; early signal registration moved to P3-37), V19 (`release.yml` split; dry run first), V20 (`deny.toml` / Dependabot / pin hygiene; audit found unmaintained `bincode` / `ttf-parser`), V21 (`check_doc` via `core::nav::resolve`), boolean-arg tidy-ups. Does **not** gate the Phase 3 exit Deferred to Phase 4 as P4-15 at the Phase 3 exit (2026-10-06). | | P3-37 | Audit fix: orphan process spin (V22) + early signals (V17) | — | done | V22: TTY guard + session-leader watchdog + stdin hangup poll (`WIKI_READER_NO_WATCHDOG=1` opts out of the leader check); V17: SIGHUP/SIGTERM/SIGINT before raw mode; `scripts/check-orphan-exit.py` runs the PTY cases in `check.sh` and CI; error output no longer panics on a dead terminal (SIGABRT race). Ships in v0.1.10. Does **not** gate the Phase 3 exit | | P3-38 | Known issue: exiting process stuck in macOS state `E` with an unread PTY master (V23) | — | dropped | [audit-v0.1.8.md](audit-v0.1.8.md). Investigated 2026-10-06 and **not reproducible as a hang**: with the master open and never read, `q` and SIGTERM exit within 1 s, and a forced exit (session leader killed) shows `?E` for about 0.6 s and then completes, on screens up to 400×1200. The same 0.6 s window appears with a drained master, so the drain hypothesis does not hold; `tcflush(OFlush)` before the forced exit made no difference and was not shipped. The property is guarded by case (v) of `check-orphan-exit` (P3-41). The two original incidents stay unexplained; the development guide's known-issues list is now empty and says what to capture if it recurs. Does **not** gate the Phase 3 exit | -| P3-39 | First crates.io release | — | todo | Prep landed in #169 (package `wiki-reader-tui`, MSRV 1.92 + CI job, `cargo-deny` + CI job, `NOTICE`, per-crate licence copies, `THIRD-PARTY-LICENSES` in tarballs, crate READMEs, SECURITY.md, Dependabot); `cargo publish --workspace --dry-run` and the release workflow dry run pass. **Gates before publishing (operator):** a second drift check and the release workflow dry run (the Phase 2 verdict and the Phase 3 exit decision are done: 2026-10-06). The first-publish release PR also drops the `v0.1.*` prerelease rule from `release.yml`, updates the release wording in `releasing.md`, README and SECURITY.md, and adds the banned-phrase check. Then `cargo publish --workspace --locked`, tag, verify `cargo install --locked wiki-reader-tui` in a fresh `CARGO_HOME`. Later: trusted publishing and the V19 workflow split. Does **not** gate the Phase 3 exit | +| P3-39 | First crates.io release | — | done | Published 2026-10-06 as v0.1.11: `wiki-reader-core`, `-media`, `-render` and `wiki-reader-tui` on crates.io, tag `v0.1.11` on the merge commit `7532065`, three tarballs with checksums, a normal (non-prerelease) GitHub release. Prep landed in #169 (package `wiki-reader-tui`, MSRV 1.92 + CI job, `cargo-deny` + CI job, `NOTICE`, per-crate licence copies, `THIRD-PARTY-LICENSES` in tarballs, crate READMEs, SECURITY.md, Dependabot); the release PR (#182) dropped the `v0.1.*` prerelease rule and added the banned-phrase check. Verified: `cargo install --locked wiki-reader-tui` (17.6 MB) and `--no-default-features` (9.0 MB) in fresh `CARGO_HOME`s report 0.1.11, the downloaded macOS arm64 tarball matches its checksum, docs.rs built. Later: trusted publishing and the V19 workflow split (P4-15). Did **not** gate the Phase 3 exit | | P3-40 | Docs: one assets directory; drop the dogfood screenshot refs | — | done | Operator request 2026-10-06 before the Phase 3 close-out. All screenshots live in `wiki/assets/` (inside the collection root, so wiki pages render them when the reader is opened on `wiki/`); root `assets/` removed; the root README, the crates.io README and the `image-protocol` example point at `wiki/assets/`; the notes moved to the [development guide](../guides/development.md#screenshots). The four table-viewer dogfood images and the links to them are gone: the dogfood-log and P3-30 descriptions are the record. Does **not** gate the Phase 3 exit | | P3-41 | Rewrite `scripts/check-orphan-exit.py` in Rust | — | done | Operator request 2026-10-06. A `check-orphan-exit` bin in `wiki-reader-tools` using rustix (`pty`, `setsid`, signals; no `unsafe`; the helper modes re-execute the binary because `std` only offers `setsid` through unsafe `pre_exec`), the same nine cases and CLI, wired into `check.sh` and CI; the script and the `python3` requirement are gone. Parity run against the Python script on macOS: identical PASS set; a stub reader that ignores the terminal fails the cases it should. Also hosts the V23 reproducer ([P3-38](#tasks)). Does **not** gate the Phase 3 exit |