Skip to content

Five-minute quick start, tested in CI #16

Open

Description

@codecapo

A 5-minute quick start in the README, backed by a test that runs the same steps in CI.

Where: README.md, an examples/ project, an integration test

Done when

  • Steps: install, infoctl init, infoctl run, add a CSV file, infoctl run again, infoctl query
  • Every command and its output in the docs is checked by a test
  • Shows the quarantine table catching a bad row
  • A new user can finish it in under 5 minutes (try it with someone)

Depends on: #14, #15

Activity

  1. added this to the 0.1.0 milestone on Oct 29, 2026
  2. codecapo commented on Nov 6, 2026

    @codecapo
    OwnerAuthor

    The design review of 2026-11-01 touches this issue. The quick start's last step, infoctl query "select * from gold.daily_revenue" (README.md:42 at a0b5e6c), shows one row per day only once ready/daily_revenue is rebuilt in full on every run, so that step waits for the @full_refresh directive (#90), while the rest of the quick start can be built and tested first as an append-only slice.

    Suggested additions to the Done-when:

    • Once compiler: implement the @full_refresh directive #90 lands, the CSV file added before the second infoctl run holds a second order, with its own order_id, for a day that already has one (for example 100, then 20 for 2026-10-29), and the test asserts that the README.md:42 query returns one row per day, with revenue 120 for that day. Appending the delta would instead give (2026-10-29, 100) and (2026-10-29, 20) side by side, because an incremental read returns only the new commit's rows (crates/storage/tests/iceberg_roundtrip.rs:77-79).
    • Until compiler: implement the @full_refresh directive #90 lands, and for good if storage: spike the replace commit route (decision D1) #72 ends with an append-only 0.1.0, the quick start shows no Ready aggregate, and its final infoctl query reads the Clean table instead of gold.daily_revenue, as does the test that checks its output. That slice needs only the fast_append commits that both write paths in crates/storage already make (crates/storage/src/lib.rs:143-148, :205-211), as long as the Clean model has no @unique_key. The RFC 0001 example has one (docs/rfcs/0001-project-files.md:89), but merging on it is Merge rows on @unique_key #35, which the quick start does not wait for, so the quick start needs a Clean model without it, before compiler: implement the @full_refresh directive #90 and after. What infoctl init writes stays with infoctl init: create an example project #8.
    • The quick start's text (README.md:36-43) agrees with the narrowed statement about incremental runs that docs: fix README, architecture and ROADMAP statements the code does not back #94 makes at README.md:23 and ROADMAP.md:13: where it shows gold.daily_revenue, it says that this table is rebuilt on every run, as @full_refresh means (docs/rfcs/0001-project-files.md:121), so the second run is not described as processing only new rows in every table.

    Work that moved to new tickets:

    Source: design review of 2026-11-01, finding C02 (with the worked example in section 2.1), section 8.3 (the candidate milestone) and section 8.5 (D1 and M5).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/docsDocs, RFCs and ADRs

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions