docs(P00): research findings — docs gap analysis + release/install root cause
---ci--- project: orca phase: 0 milestone: v0.10 status: research ---/ci---
This commit is contained in:
Jon Chery
@@ -0,0 +1,140 @@
|
||||
# Research: v0.10 Docs & Install Milestone
|
||||
|
||||
## Documentation landscape in the orca tree
|
||||
|
||||
### What exists today
|
||||
|
||||
The `docs/` directory contains four files:
|
||||
|
||||
- `docs/install.md` — install guide (user-level, system-level, version
|
||||
pinning, in-place update, troubleshooting). Accurate for v0.5-v0.8
|
||||
but does not mention the v0.9 multi-namespace layout, `--config`, or
|
||||
`--no-deprecation-warnings`.
|
||||
- `docs/docker.md` — Docker image guide. Still documents `orca daemon`
|
||||
(deprecated in v0.9).
|
||||
- `docs/namespace.md` — namespace and paths. Documents the **v0.8 flat
|
||||
layout** (`~/.orca/orca.db`, `ca.crt`, `ca.key`, `server.crt`,
|
||||
`server.key`). Does NOT document the v0.9 multi-namespace layout
|
||||
(`cluster/`, `_defaults/`, per-ns `db/jobs/alloc/ns.md`), `orca ns`
|
||||
subcommands, or the `_defaults` implicit root (D-159/D-185/D-187).
|
||||
- `docs/security-scanning.md` — gosec + govulncheck + gitleaks guide.
|
||||
Accurate; no v0.9 drift.
|
||||
|
||||
### What's missing (the gap this milestone closes)
|
||||
|
||||
1. **No CLI reference doc.** The entire CLI command surface (init, job,
|
||||
node, ns, cert, daemon, doctor, status, audit, version) is
|
||||
undocumented in `docs/`. The README subcommand table is stale (lists
|
||||
only version/init/status/node/job with fake "Phase N" statuses,
|
||||
missing cert/daemon/doctor/audit/ns/node-capacity/node-key-reset).
|
||||
2. **No jobspec reference doc.** The markdown frontmatter schema (kinds,
|
||||
blocks, CEL subset, validation rules, body semantics) is
|
||||
undocumented. Operators must read `internal/jobspec/markdown.go` and
|
||||
`internal/spec/schema/schema.go` source.
|
||||
3. **No ingress/Traefik doc.** The service→Traefik mapping, R-007
|
||||
socket-vs-TCP-bind, atomic reload, drain, TLS — all undocumented.
|
||||
4. **No examples directory.** `testdata/` holds legacy HCL fixtures
|
||||
(`hello.hcl`, `fail.hcl`) for Go tests, not operator-facing
|
||||
examples. No worked full-stack demo exists.
|
||||
5. **README is stale.** Status line says "v0.1: Foundation".
|
||||
Subcommand table missing 5 commands. Install `--version` example
|
||||
pins v0.4.2. Update-in-place example references v0.4.1→v0.4.2.
|
||||
Development section omits 4 make targets.
|
||||
|
||||
### Prior art for CLI reference docs
|
||||
|
||||
- **Nomad**: `nomad job` / `nomad node` / `nomad agent` reference pages,
|
||||
one per subcommand, with flag tables and JSON examples. Orca's
|
||||
single-file `docs/cli.md` is simpler (one file vs a subdirectory) but
|
||||
follows the same flag-table + example convention.
|
||||
- **kubectl**: `kubectl reference` + per-command pages. Too heavy for
|
||||
orca; the single-file model fits the minimalist ethos.
|
||||
- **Docker CLI**: `docker run` reference with flag tables. Matches the
|
||||
shape orca's `docs/cli.md` will take.
|
||||
|
||||
### Prior art for example jobspecs
|
||||
|
||||
- **Nomad example jobs**: `nomad-job-spec.example` files in the Nomad
|
||||
repo showing service + job + sysbatch patterns. Orca's
|
||||
`examples/full-stack/` mirrors this with 5 markdown jobspecs covering
|
||||
Service/Job/DaemonSet + task groups + volumes + replication.
|
||||
- **Kubernetes examples**: `examples/` directory with yaml
|
||||
deployments/services/ingress. Orca's equivalent is the 5 jobspecs +
|
||||
rendered Traefik/systemd artifacts.
|
||||
|
||||
## Release/install pipeline research
|
||||
|
||||
### Root cause of the v0.4.5 install
|
||||
|
||||
Verified via the Gitea API:
|
||||
|
||||
```
|
||||
GET /api/v1/repos/coreci/orca/releases/latest
|
||||
→ tag_name: "v0.8.15"
|
||||
|
||||
GET /api/v1/repos/coreci/orca/releases/tags/v0.8.15
|
||||
→ attachments: [] (zero binary assets)
|
||||
```
|
||||
|
||||
The v0.8.x releases (v0.8.0 through v0.8.15) all shipped with **zero
|
||||
binary assets attached**. Only `v0.4.5` carries a tarball
|
||||
(`orca-v0.4.5-linux-amd64.tar.gz`).
|
||||
|
||||
`scripts/install.sh:70-78` resolves "latest" → v0.8.15, then
|
||||
`install.sh:96-104` looks for `orca-v0.8.15-linux-amd64.tar.gz` in
|
||||
v0.8.15's assets. Since the asset is missing, install.sh errors out
|
||||
(`could not find asset ... in release v0.8.15`). The v0.4.5 install
|
||||
came from an earlier run or a pinned `--version`.
|
||||
|
||||
### Why v0.8.x releases have no assets
|
||||
|
||||
`scripts/release.sh:132-136` calls `tea releases create "$VERSION" ...
|
||||
--asset "$TARBALL"`. The script builds the tarball (line 98) and passes
|
||||
it to `tea`. Two likely failure modes:
|
||||
|
||||
1. **Host arch mismatch**: `release.sh:89-95` builds for the host arch
|
||||
(`uname -m`). If the CI runner or dev machine is arm64, it produces
|
||||
`orca-v0.8.15-linux-arm64.tar.gz`, but `install.sh` looks for
|
||||
`linux-amd64`. The `.coreci.yml:121` release step hardcodes
|
||||
`--asset orca-${VERSION}-linux-amd64.tar.gz`, so the CI runner must
|
||||
be amd64 — but `release.sh` run locally on an arm64 dev machine
|
||||
produces the wrong arch.
|
||||
2. **Silent asset drop**: `tea releases create` has been observed to
|
||||
succeed (exit 0) without attaching the asset in some tea versions.
|
||||
The script treats `tea`'s exit code as success without verifying the
|
||||
asset actually appears in the release.
|
||||
|
||||
### Fix approach (REQ-097, REQ-098)
|
||||
|
||||
**release.sh**:
|
||||
- Cross-build `linux-amd64` explicitly via
|
||||
`GOOS=linux GOARCH=amd64 go build`, regardless of host arch.
|
||||
- After `tea releases create`, query
|
||||
`/api/v1/repos/$OWNER/$REPO/releases/tags/$VERSION` and assert the
|
||||
tarball appears in `attachments`. If not, retry once, then fail
|
||||
loudly with a clear error.
|
||||
|
||||
**install.sh**:
|
||||
- Add an asset fallback walk: if the resolved release (latest or
|
||||
pinned) lacks the matching tarball, query
|
||||
`/releases?limit=20`, walk backward, and use the most recent release
|
||||
that carries the `orca-<ver>-<os>-<arch>.tar.gz` asset. Print a
|
||||
clear warning.
|
||||
- Add `--check` dry-run mode (D-194) that prints the version + asset URL
|
||||
+ install path without writing.
|
||||
|
||||
## Persona assessment (PERSONAS.md)
|
||||
|
||||
This milestone touches two territories:
|
||||
|
||||
1. **`scripts/` (release.sh, install.sh)** — bash scripts, not Go.
|
||||
Backend-engineer territory (API-adjacent tooling). The fix is
|
||||
cross-build + API verification + fallback walk.
|
||||
2. **`docs/` + `examples/` + `README.md`** — markdown documentation.
|
||||
Lead-developer territory (coordination + cross-cutting docs).
|
||||
|
||||
No data-engineer work (no schema/migration changes). No
|
||||
frontend-engineer work (no UI). The data-engineer persona is
|
||||
deactivated for this milestone. A docs-engineer custom persona is
|
||||
created for P2/P3/P4 (markdown authoring with codebase-grounded
|
||||
factual claims).
|
||||
Reference in New Issue
Block a user