docs: align README quick start with main
This commit is contained in:
codex-bot-andresmgsl
parent
616ada76b9
commit
32e17246a2
4 changed files with 114 additions and 11 deletions
16
README.md
16
README.md
|
|
@ -15,13 +15,13 @@ takes arguments, does its work, and stores no credential, ever.
|
|||
## Install
|
||||
|
||||
```sh
|
||||
curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | bash
|
||||
curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash
|
||||
```
|
||||
|
||||
That installs the **latest release**: the installer resolves the newest tag
|
||||
by following GitHub's `releases/latest` redirect (no API, no token) and
|
||||
downloads that tag's source tarball — which, for a pure-bash tree, *is* the
|
||||
package. Three channels from the same script; `RIG_REF` picks:
|
||||
This README tracks `main`, so the quick start installs that same development
|
||||
tree. To install a stable version instead, use the latest-release or pinned-tag
|
||||
channel and follow the documentation shipped with that version. Three channels
|
||||
come from the same script; `RIG_REF` picks:
|
||||
|
||||
```sh
|
||||
curl -fsSL .../install.sh | bash # the latest release
|
||||
|
|
@ -32,12 +32,6 @@ curl -fsSL .../install.sh | RIG_REF=main bash # the development tree
|
|||
A tag outranks a branch of the same name (the pin must win); anything that
|
||||
is not a tag falls back to `refs/heads/<ref>`.
|
||||
|
||||
> **Transitional, until 0.1.0 is cut** (right after rig#32 lands): rig has
|
||||
> no GitHub release yet, so the default channel has nothing to resolve —
|
||||
> it **fails loudly** naming `RIG_REF=main` as the way to install today,
|
||||
> and never silently falls back to main. Once 0.1.0 exists, the plain
|
||||
> `curl | bash` above is the normal path.
|
||||
|
||||
The layout, under the install root (`~/.local/share/rig`):
|
||||
|
||||
```
|
||||
|
|
|
|||
69
docs/superpowers/plans/2026-07-20-readme-install-channel.md
Normal file
69
docs/superpowers/plans/2026-07-20-readme-install-channel.md
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
# README Install-Channel Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Ensure the `main` README installs the same development tree whose CLI it documents.
|
||||
|
||||
**Architecture:** Keep installer channel behavior unchanged and correct the documentation entry point. Add one source-level regression assertion to the existing dependency-free CLI suite.
|
||||
|
||||
**Tech Stack:** Bash, Markdown, the existing `test/cli.sh` assertion harness.
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- The stable latest-release and pinned-tag channels remain documented.
|
||||
- No compatibility aliases or installer behavior changes.
|
||||
- The regression must run inside the existing `bash test/cli.sh` CI step.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Align the README install channel
|
||||
|
||||
**Files:**
|
||||
- Modify: `README.md`
|
||||
- Test: `test/cli.sh`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: The existing `check` helper in `test/cli.sh`.
|
||||
- Produces: A README quick-start command containing `RIG_REF=main bash`.
|
||||
|
||||
- [ ] **Step 1: Write the failing regression test**
|
||||
|
||||
Add this assertion near the existing README checks in `test/cli.sh`:
|
||||
|
||||
```bash
|
||||
check "README: the main-branch quick start installs the documented tree" 0 "" \
|
||||
grep -qF 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash' "$ROOT/README.md"
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify the test fails for the reported mismatch**
|
||||
|
||||
Run: `bash test/cli.sh`
|
||||
|
||||
Expected: one failure named `README: the main-branch quick start installs the documented tree` because the full command lacks `RIG_REF=main`.
|
||||
|
||||
- [ ] **Step 3: Make the minimal README correction**
|
||||
|
||||
Change the primary install command to:
|
||||
|
||||
```sh
|
||||
curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash
|
||||
```
|
||||
|
||||
Explain that the README tracks `main`; retain examples for the default latest-release and pinned-tag channels, and delete the obsolete transitional notice about cutting 0.1.0.
|
||||
|
||||
- [ ] **Step 4: Verify the focused and full suites pass**
|
||||
|
||||
Run: `bash test/cli.sh`
|
||||
|
||||
Expected: all CLI assertions pass with zero failures.
|
||||
|
||||
Run: `bash test/release.sh`
|
||||
|
||||
Expected: all release assertions pass with zero failures.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add README.md test/cli.sh
|
||||
git commit -m "docs: align README quick start with main"
|
||||
```
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
# README install-channel alignment
|
||||
|
||||
## Problem
|
||||
|
||||
The landing-page README describes the unreleased CLI on `main`, including
|
||||
the `*-server` and `*-box` role names, but its first install command selects
|
||||
the latest release. At present that is 0.2.0, whose CLI accepts the retired
|
||||
role names instead. A reader following the quick start therefore installs a
|
||||
CLI that rejects the README's examples.
|
||||
|
||||
## Decision
|
||||
|
||||
The README is documentation for the branch that contains it. Its primary
|
||||
install command will explicitly set `RIG_REF=main`, making the installed tree
|
||||
match the commands documented below it. The stable channel remains documented
|
||||
next to the development and pinned channels, but is no longer presented as the
|
||||
matching prerequisite for the `main` README's quick start.
|
||||
|
||||
The obsolete pre-0.1.0 transitional notice will be removed. No installer
|
||||
behavior, role compatibility aliases, or release process will change.
|
||||
|
||||
## Regression protection
|
||||
|
||||
The dependency-free CLI test suite will assert that the README's full GitHub
|
||||
installer command opts into `RIG_REF=main`. This directly protects the broken
|
||||
onboarding path without trying to infer semantic compatibility between every
|
||||
README example and every historical release.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- The first complete installer command in `README.md` installs `main`.
|
||||
- The README still explains how to install the latest release and a pinned tag.
|
||||
- The stale “until 0.1.0 is cut” notice is absent.
|
||||
- `bash test/cli.sh` fails on the old README and passes after the documentation
|
||||
correction.
|
||||
|
||||
|
|
@ -428,6 +428,10 @@ check "bootstrap: --users does not reach the tenant roles" 2 "unknown flag" \
|
|||
check "bootstrap: usage explains why tenants take no --users" 0 "box-minted GUEST" \
|
||||
"$ROOT/commands/bootstrap.sh" --help
|
||||
# --- README: the box rename (#12) --------------------------------------------
|
||||
# The README on main documents main's CLI, so its first full install command
|
||||
# must opt into that tree instead of silently selecting an older release.
|
||||
check "README: the main-branch quick start installs the documented tree" 0 "" \
|
||||
grep -qF 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash' "$ROOT/README.md"
|
||||
# The philosophy line must point at heavy-duty/box — the old claudebox slug
|
||||
# only works through a GitHub redirect that one squatted rename away from
|
||||
# breaking (box's own installer was already bitten by the rename once). A
|
||||
|
|
|
|||
Loading…
Reference in a new issue