Skip to content

docs: truth pass — README/nav-map/checklist match the v0.8 surface + release policy#307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
saadqbal merged 2 commits into from
Jul 14, 2026
Merged

docs: truth pass — README/nav-map/checklist match the v0.8 surface + release policy #307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9689b41
docs: truth pass — README/nav-map/checklist match the v0.8 surface; r…
LukasWodka Jul 14, 2026
49c6f40
docs: refresh README latest-release refs v0.8.0 -> v0.9.1 (#296)
LukasWodka Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/workflows/release.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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):
#
Expand Down
22 changes: 16 additions & 6 deletions README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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.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):

`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).
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)).

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)).

Expand DownExpand Up@@ -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 homescreen (#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. **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).

Expand Down
25 changes: 11 additions & 14 deletions docs/cli-navigation.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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).

---

Expand All@@ -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).
Expand DownExpand Up@@ -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
Expand DownExpand Up@@ -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 / `<table>`) 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 / `<table>`) 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)).
13 changes: 11 additions & 2 deletions scripts/RELEASE_CHECKLIST.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand All@@ -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
Expand Down
Loading