From 9689b410f2a579d8162123253c9a8815eb18e979 Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Tue, 14 Jul 2026 14:26:39 +0200 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20truth=20pass=20=E2=80=94=20README/n?= =?UTF-8?q?av-map/checklist=20match=20the=20v0.8=20surface;=20release=20po?= =?UTF-8?q?licy=20(#296)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every claim re-verified against the actual command tree (go run ./cmd/tracebloc --help + each subcommand on develop @ 5af9a80): README: - v0.3.0 status blurb -> v0.8.0 latest release + a lifecycle command table (login/logout/auth, client/status, resources show+set, data ingest/list/delete/validate, cluster info, doctor, delete, version/completion/home screen); notes what landed post-v0.8.0 - 15-of-16 tasks -> all 16 (semantic_segmentation shipped in #247; registry verified: 16x CLISupported, zero false) - roadmap tail: 9-of-10-modalities + v0.2/v0.3 story -> v0.2-v0.8 arc; semseg removed from Next (done); cloud-source kept (backed by RFC-0002 + the in-help 1 GiB cap copy) - links the navigation map docs/cli-navigation.md: - stale-basis disclaimer removed (was develop @ 27c5392) - resources set (#241) + status-aware home screen (#244) un-dashed — both merged; proposed classDef dropped - nonexistent home-screen-spec.md references removed (point at #244) - doctor node: top-level doctor shipped, cluster doctor = hidden alias (pinned by TestClusterCmd_DoctorIsHiddenAlias) - known-gaps list pruned to what is still true (offboard partial teardown still exits 0 — re-verified in delete.go) scripts/RELEASE_CHECKLIST.md: - 5-line release policy: trigger = customer-visible merge or weekly, owner = DevEx squad (role, not person) - EKS smoke: dataset push -> data ingest; v0.1-ticket pre-flight genericized release.yml: header comment claimed release notes come from CHANGELOG.md — no such file exists; it's generate_release_notes: true. Fixes #296 Co-Authored-By: Claude Fable 5 --- .github/workflows/release.yml | 3 ++- README.md | 22 ++++++++++++++++------ docs/cli-navigation.md | 25 +++++++++++-------------- scripts/RELEASE_CHECKLIST.md | 13 +++++++++++-- 4 files changed, 40 insertions(+), 23 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index bef10b42..4e63cb11 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -12,7 +12,8 @@ # `https://github.com/tracebloc/cli/releases/latest/download/install.sh` # resolves to the right script for that release # - GitHub Release with all of the above attached + release-notes -# body generated from CHANGELOG.md +# body auto-generated by GitHub from the merged PRs +# (generate_release_notes: true — there is no CHANGELOG.md) # # Verification (one-liner customers run to check the signature): # diff --git a/README.md b/README.md index 4b57d786..061d745f 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,25 @@ # tracebloc CLI -The customer-facing CLI for the tracebloc declarative ingestion path. Wraps the same `POST /internal/submit-ingestion-run` protocol the [`tracebloc/ingestor`](https://github.com/tracebloc/client/tree/main/ingestor) Helm chart uses, so any cluster running the parent [`tracebloc/client`](https://github.com/tracebloc/client) chart can be targeted directly from a developer's workstation. +The customer-facing CLI for tracebloc: sign in, provision this machine as a client, ingest and manage datasets, inspect and diagnose the environment, size tracebloc's compute share, and offboard — no Helm, no YAML, no kubectl. The data path wraps the same `POST /internal/submit-ingestion-run` protocol the [`tracebloc/ingestor`](https://github.com/tracebloc/client/tree/main/ingestor) Helm chart uses, so any cluster running the parent [`tracebloc/client`](https://github.com/tracebloc/client) chart can be targeted directly from a developer's workstation. ## Status -**v0.3.0 is released** — the latest stable [release](https://github.com/tracebloc/cli/releases/latest), cut from `develop`. It builds on v0.2.0's guided `data ingest` and `dataset rm` with a new `dataset list` command plus home-screen / output polish (clearer copy, guided-first framing). The binary implements `version`, `completion`, `data validate`, `cluster info`, and the full `data ingest` / `dataset list` / `dataset rm` flow — local schema validation, cluster discovery, data staging, submission, and Job watching, end to end. +**v0.8.0 is the latest release** — the latest stable [release](https://github.com/tracebloc/cli/releases/latest), cut from `develop`. The binary covers the whole client lifecycle (this table describes `develop`, the tree this README lives on): -`data ingest` covers **15 of 16 task categories**: `image_classification`, `object_detection`, `keypoint_detection`, `text_classification`, `token_classification`, `sentence_pair_classification`, `masked_language_modeling`, `causal_language_modeling`, `seq2seq`, `embeddings`, `tabular_classification`, `tabular_regression`, `time_series_forecasting`, `time_series_classification`, and `time_to_event_prediction`. `semantic_segmentation` is pending mask-sidecar support upstream ([data-ingestors#136](https://github.com/tracebloc/data-ingestors/issues/136)). +| Area | Commands | +|---|---| +| Your account | `login` (browser device flow), `logout`, `auth status` | +| This machine's client | `client` (guided provisioning), `client status`, `resources` / `resources set` (compute share), `delete` (offboard) | +| Datasets | `data ingest`, `data list`, `data delete`, `data validate` | +| Environment | `cluster info`, `doctor` (✔/⚠/✖ health checks + remedies) | +| Meta | `version`, `completion`, and the status-aware home screen — run bare `tracebloc` (or its alias `tb`) | -The release pipeline ships [`v0.3.0`](https://github.com/tracebloc/cli/releases/latest) as **cosign-signed, multi-arch binaries** — Linux (`amd64`, `arm64`, `386`, `arm`), macOS (`amd64`, `arm64`), and Windows (`amd64`, `arm64`) — each with `SHA256SUMS` and the install scripts. GitHub releases plus the cosign-verified `install.sh` are the install path — see [Customer experience](#customer-experience) or [build from source](#building-from-source). +Landed on `develop` after the v0.8.0 cut (ships with the next release): `resources` / `resources set`, the status-aware home screen, top-level `doctor` (v0.8.0 has it as `cluster doctor`), and `semantic_segmentation` support. The full navigation map — every command, decision point, and exit path — lives in [`docs/cli-navigation.md`](docs/cli-navigation.md). + +`data ingest` covers **all 16 task categories**: `image_classification`, `object_detection`, `keypoint_detection`, `semantic_segmentation`, `text_classification`, `token_classification`, `sentence_pair_classification`, `masked_language_modeling`, `causal_language_modeling`, `seq2seq`, `embeddings`, `tabular_classification`, `tabular_regression`, `time_series_forecasting`, `time_series_classification`, and `time_to_event_prediction` (`semantic_segmentation` — the 16th — landed with [#247](https://github.com/tracebloc/cli/pull/247)). + +The release pipeline ships every release as **cosign-signed, multi-arch binaries** — Linux (`amd64`, `arm64`, `386`, `arm`), macOS (`amd64`, `arm64`), and Windows (`amd64`, `arm64`) — each with `SHA256SUMS` and the install scripts. GitHub releases plus the cosign-verified `install.sh` are the install path — see [Customer experience](#customer-experience) or [build from source](#building-from-source). The Helm chart remains a sibling interface for the Kubernetes-native workflow: `helm install tracebloc/ingestor --set-file ingestConfig=./ingest.yaml` (see the chart's [README](https://github.com/tracebloc/client/blob/develop/ingestor/README.md)). @@ -115,9 +125,9 @@ All v0.1 phases are merged: | 4 | [#152](https://github.com/tracebloc/client/issues/152) | Submit to jobs-manager + watch ingestor Job + summary | ✅ | | 5 | [#153](https://github.com/tracebloc/client/issues/153) | GitHub Releases + install.sh distribution (Homebrew tap dropped — [#299](https://github.com/tracebloc/cli/issues/299)) | ✅ — [`v0.1.0`](https://github.com/tracebloc/cli/releases/tag/v0.1.0) released (stable, 8-platform) | -Beyond the original phases, `data ingest` was widened from image-classification-only to 9 of 10 modalities, and the test suite gained unit-coverage wins plus a kind-based integration harness for the real-I/O seams. +Beyond the original phases, `data ingest` was widened from image-classification-only to all 16 task categories, and the test suite gained unit-coverage wins plus a kind-based integration harness for the real-I/O seams. -**v0.2.0** added a friendlier guided `data ingest` and `dataset rm` on the home screen (#44, #47). **v0.3.0** added the `dataset list` command (#53) plus home-screen / output-spacing polish and feedback-copy refinements (#52, #56). **Next:** cloud-source ingestion (S3/GCS/HTTPS) for datasets above the 1 GiB local cap; `semantic_segmentation` ([data-ingestors#136](https://github.com/tracebloc/data-ingestors/issues/136)). Smaller follow-ups are tracked as [open issues](https://github.com/tracebloc/cli/issues). +**v0.2–v0.3** added guided `data ingest`, `dataset list` / `dataset rm`, and home-screen polish. **v0.4–v0.5** added browser sign-in (`login` / `logout` / `auth status`), one-command client provisioning, `cluster doctor`, and the `dataset` → `data` rename (RFC-0001). **v0.6–v0.8** hardened ingest end to end: namespace discovery, plain-language copy, flag renames, flexible file-or-folder input, tabular schema confirmation, and the five text tasks. Since the v0.8.0 cut, `develop` gained `resources` / `resources set`, the status-aware home screen, top-level `doctor`, and `semantic_segmentation` ([#247](https://github.com/tracebloc/cli/pull/247)). **Next:** cloud-source ingestion (S3/GCS/HTTPS) for datasets above the 1 GiB local cap (RFC-0002 non-goal, planned). Smaller follow-ups are tracked as [open issues](https://github.com/tracebloc/cli/issues). Epic: [tracebloc/client#147](https://github.com/tracebloc/client/issues/147). diff --git a/docs/cli-navigation.md b/docs/cli-navigation.md index d668f9d5..f8ce4008 100644 --- a/docs/cli-navigation.md +++ b/docs/cli-navigation.md @@ -2,11 +2,9 @@ **The single source of truth for how a user moves through the CLI.** Every command, decision point, and place a user can end up. Diagrams are [Mermaid](https://mermaid.js.org) — they render natively on GitHub and in the docs, and this file is version-controlled, so **edit this file + open a PR to change the map** (that PR is where we discuss flow changes). -> **Basis:** `develop` @ `27c5392`. Two things are marked distinctly: -> - **`resources show`** has shipped to `develop` (#237) → drawn solid; **`resources set`** (#241) is still on a feature branch → drawn **dashed / "not shipped"**. -> - The **status-aware home screen** (greeting + sign-in + environment) is a *proposed* redesign (see `home-screen-spec.md`); today's home screen is **stateless** (same for everyone). Proposed bits are dashed. +The map tracks `develop`. Everything drawn solid is shipped there — including `resources show` (#237), `resources set` (#241), and the status-aware home screen (#244). -**How to read it:** `{diamond}` = decision · `[box]` = step · `([rounded])` = where you end up · green = exit 0 · red = non-zero exit · grey dashed = hidden (installer/back-compat) · orange dashed = proposed / not-yet-shipped. +**How to read it:** `{diamond}` = decision · `[box]` = step · `([rounded])` = where you end up · green = exit 0 · red = non-zero exit · grey dashed = hidden (installer/back-compat). --- @@ -32,12 +30,11 @@ flowchart TD ENVC --> dd["data delete"] ENVC --> dv["data validate (local only, no cluster)"] ENVC --> ci["cluster info"] - ENVC --> doc["doctor (a.k.a. cluster doctor today)"] - ENVC --> res["resources show"] - ENVC -.-> resset["resources set"]:::proposed + ENVC --> doc["doctor (cluster doctor = hidden alias)"] + ENVC --> res["resources (bare = show)"] + ENVC --> resset["resources set"] classDef hidden fill:#eee,stroke:#999,stroke-dasharray:3 3,color:#666; - classDef proposed fill:#fff5e6,stroke:#e0a24a,stroke-dasharray:5 5; ``` `tb` is a convenience alias for `tracebloc` (installer-placed symlink; identical behavior). Aliases kept one deprecation cycle: `data`↔`dataset`, `data ingest`↔`push`, `data delete`↔`rm`. Hidden nodes are fully functional but off the everyday surface (installer / back-compat). @@ -122,7 +119,7 @@ flowchart TD --- -## 4. `resources` — show & set *(`show` shipped #237, on `develop`; `set` on feature branch #241, not yet on `develop`)* +## 4. `resources` — show & set *(both shipped on `develop`: `show` #237, `set` #241)* ```mermaid flowchart TD @@ -184,8 +181,8 @@ flowchart TD ## Known gaps / decisions (raise in review) -1. **Home screen is stateless today.** The status-aware redesign (greeting + sign-in + environment + compute) in `home-screen-spec.md` is *proposed* — it's the target, not current behavior. -2. **`delete` (offboard) exits 0 even on a *partial/degraded* teardown** — it warns but never returns non-zero, so a script can't detect an incomplete offboard. A dedicated non-zero "partial offboard" code would close this. -3. **`resources set` is unshipped on `develop`.** `show` shipped via #237 (now on `develop`); `set` lands via #241 (still on a feature branch). -4. **`cluster doctor` → `tb doctor`** rename is decided (home-screen spec); the map already shows `doctor`. `cluster info`'s home (stay under `cluster`, or also promote) is open. -5. Terminology in the live copy (client / cluster / ``) is pre-cleanup; the map uses the agreed target words (secure environment, etc.). The rename wave aligns the code later. +1. **`delete` (offboard) exits 0 even on a *partial/degraded* teardown** — it warns but never returns non-zero, so a script can't detect an incomplete offboard. A dedicated non-zero "partial offboard" code would close this. +2. **`cluster info`'s home is open** — the `doctor` promotion shipped (top-level `doctor`, with `cluster doctor` kept as a hidden alias); whether `cluster info` stays under `cluster` or is also promoted is undecided. +3. Terminology in the live copy (client / cluster / `
`) is pre-cleanup; the map uses the agreed target words (secure environment, etc.). The rename wave aligns the code later. + +Resolved since the first cut of this map: the status-aware home screen shipped ([#244](https://github.com/tracebloc/cli/pull/244) — greeting + sign-in + environment state on bare `tracebloc`/`tb`), and `resources set` shipped ([#241](https://github.com/tracebloc/cli/pull/241)). diff --git a/scripts/RELEASE_CHECKLIST.md b/scripts/RELEASE_CHECKLIST.md index 315dd24a..a8197530 100644 --- a/scripts/RELEASE_CHECKLIST.md +++ b/scripts/RELEASE_CHECKLIST.md @@ -5,6 +5,15 @@ triggers it. This document covers the per-release manual steps that either ARE or AREN'T automated, so the on-call engineer doesn't have to reverse-engineer the surface area on release day. +## Release policy + +- **Trigger:** cut a release when a customer-visible feature merges + to `develop`, or weekly if anything customer-visible is sitting + unreleased — whichever comes first. Don't let `develop` drift + releases behind (the v0.8 gap reached 46 unreleased commits). +- **Owner:** the DevEx squad (role, not a person) cuts the tag and + walks this checklist. + ## What runs automatically on `git push origin v0.1.0` 1. `.github/workflows/release.yml` fires. @@ -31,10 +40,10 @@ The release-cutter runs these on tag day. ### 1. Pre-flight -- [ ] All v0.1 phase tickets closed (`#147-#153`) +- [ ] No release-blocking tickets open on the milestone - [ ] `develop` is green on CI + Bugbot - [ ] Local smoke: `go test -race ./...` passes -- [ ] Real EKS smoke: `tracebloc dataset push ./cats-dogs ...` +- [ ] Real EKS smoke: `tracebloc data ingest ./cats-dogs ...` end-to-end reports the expected row count ### 2. Tag + push From 49c6f40dddec2699b2d4f7316fcd925bbd995361 Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Tue, 14 Jul 2026 17:05:21 +0200 Subject: [PATCH 2/2] docs: refresh README latest-release refs v0.8.0 -> v0.9.1 (#296) Addresses Asad's review on #307: this truth pass predated the v0.9.0 and v0.9.1 cuts, so a few version claims went stale. - Status blurb: "v0.8.0 is the latest release" -> "v0.9.1 is the latest release". - The post-v0.8.0 "ships with the next release" framing for resources / status-aware home screen / top-level doctor / semantic_segmentation -> "Shipped in v0.9.0" (they released in v0.9.0, no longer "next"). - Roadmap tail: "Since the v0.8.0 cut, develop gained ..." -> a "v0.9 added ...; v0.9.1 is the current latest" entry, extending the v0.2-v0.8 arc. Historical v0.8.0 references (the v0.8.0 cut, cluster doctor in v0.8.0) kept as deliberate contrasts. Homebrew tap stays dropped (#300) - no reintroduction. Co-Authored-By: Claude Fable 5 --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 061d745f..a7b5b910 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ The customer-facing CLI for tracebloc: sign in, provision this machine as a clie ## Status -**v0.8.0 is the latest release** — the latest stable [release](https://github.com/tracebloc/cli/releases/latest), cut from `develop`. The binary covers the whole client lifecycle (this table describes `develop`, the tree this README lives on): +**v0.9.1 is the latest release** — the latest stable [release](https://github.com/tracebloc/cli/releases/latest), cut from `develop`. The binary covers the whole client lifecycle (this table describes `develop`, the tree this README lives on): | Area | Commands | |---|---| @@ -16,7 +16,7 @@ The customer-facing CLI for tracebloc: sign in, provision this machine as a clie | Environment | `cluster info`, `doctor` (✔/⚠/✖ health checks + remedies) | | Meta | `version`, `completion`, and the status-aware home screen — run bare `tracebloc` (or its alias `tb`) | -Landed on `develop` after the v0.8.0 cut (ships with the next release): `resources` / `resources set`, the status-aware home screen, top-level `doctor` (v0.8.0 has it as `cluster doctor`), and `semantic_segmentation` support. The full navigation map — every command, decision point, and exit path — lives in [`docs/cli-navigation.md`](docs/cli-navigation.md). +Shipped in v0.9.0, after the v0.8.0 cut: `resources` / `resources set`, the status-aware home screen, top-level `doctor` (v0.8.0 had it only as `cluster doctor`), and `semantic_segmentation` support. The full navigation map — every command, decision point, and exit path — lives in [`docs/cli-navigation.md`](docs/cli-navigation.md). `data ingest` covers **all 16 task categories**: `image_classification`, `object_detection`, `keypoint_detection`, `semantic_segmentation`, `text_classification`, `token_classification`, `sentence_pair_classification`, `masked_language_modeling`, `causal_language_modeling`, `seq2seq`, `embeddings`, `tabular_classification`, `tabular_regression`, `time_series_forecasting`, `time_series_classification`, and `time_to_event_prediction` (`semantic_segmentation` — the 16th — landed with [#247](https://github.com/tracebloc/cli/pull/247)). @@ -127,7 +127,7 @@ All v0.1 phases are merged: Beyond the original phases, `data ingest` was widened from image-classification-only to all 16 task categories, and the test suite gained unit-coverage wins plus a kind-based integration harness for the real-I/O seams. -**v0.2–v0.3** added guided `data ingest`, `dataset list` / `dataset rm`, and home-screen polish. **v0.4–v0.5** added browser sign-in (`login` / `logout` / `auth status`), one-command client provisioning, `cluster doctor`, and the `dataset` → `data` rename (RFC-0001). **v0.6–v0.8** hardened ingest end to end: namespace discovery, plain-language copy, flag renames, flexible file-or-folder input, tabular schema confirmation, and the five text tasks. Since the v0.8.0 cut, `develop` gained `resources` / `resources set`, the status-aware home screen, top-level `doctor`, and `semantic_segmentation` ([#247](https://github.com/tracebloc/cli/pull/247)). **Next:** cloud-source ingestion (S3/GCS/HTTPS) for datasets above the 1 GiB local cap (RFC-0002 non-goal, planned). Smaller follow-ups are tracked as [open issues](https://github.com/tracebloc/cli/issues). +**v0.2–v0.3** added guided `data ingest`, `dataset list` / `dataset rm`, and home-screen polish. **v0.4–v0.5** added browser sign-in (`login` / `logout` / `auth status`), one-command client provisioning, `cluster doctor`, and the `dataset` → `data` rename (RFC-0001). **v0.6–v0.8** hardened ingest end to end: namespace discovery, plain-language copy, flag renames, flexible file-or-folder input, tabular schema confirmation, and the five text tasks. **v0.9** added `resources` / `resources set`, the status-aware home screen, top-level `doctor`, and `semantic_segmentation` ([#247](https://github.com/tracebloc/cli/pull/247)); v0.9.1 is the current latest. **Next:** cloud-source ingestion (S3/GCS/HTTPS) for datasets above the 1 GiB local cap (RFC-0002 non-goal, planned). Smaller follow-ups are tracked as [open issues](https://github.com/tracebloc/cli/issues). Epic: [tracebloc/client#147](https://github.com/tracebloc/client/issues/147).