the sixty second snippet, compiled and run as it is printed - #318
Merged
Merged
Conversation
A quickstart is the most read and least compiled code a project has. It lives in a README, it is copied by hand, and it goes wrong quietly, a rename at a time, until a reader's first five minutes go on an error message instead of on a database. So the snippet is a program. crates/zu-snippets holds it as an example and a test holds the README to it character for character, then runs it in a directory of its own and checks what it printed. Compiling proves the names still exist; running proves the statements still parse, the file still opens and the two lines on the page are the two lines it prints. The package exists because a crate cannot depend on itself under a second name, and the snippet has to say `zudb`, which is what a reader types after `cargo add zudb` and not what this crate is called in this workspace. crates/zu/benches/convert.rs is reformatted, which is nothing to do with any of this and is what `cargo fmt --all --check` wants.
20 tasks
tamnd
added a commit
that referenced
this pull request
Aug 19, 2026
A quickstart is the most read and least compiled code a project has. It lives in a README, it is copied by hand, and it goes wrong quietly, a rename at a time, until a reader's first five minutes go on an error message instead of on a database. So the snippet is a program. crates/zu-snippets holds it as an example and a test holds the README to it character for character, then runs it in a directory of its own and checks what it printed. Compiling proves the names still exist; running proves the statements still parse, the file still opens and the two lines on the page are the two lines it prints. The package exists because a crate cannot depend on itself under a second name, and the snippet has to say `zudb`, which is what a reader types after `cargo add zudb` and not what this crate is called in this workspace. crates/zu/benches/convert.rs is reformatted, which is nothing to do with any of this and is what `cargo fmt --all --check` wants.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DX2 (#168): the 60-second snippet works verbatim in Python and Rust. This is the Rust half; the Python half is tamnd/zu-python#11, merged.
A quickstart is the most read and least compiled code a project has. It lives in a README, it is copied by hand, and it goes wrong quietly, a rename at a time, until a reader's first five minutes go on an error message instead of on a database. So the snippet is a program here.
crates/zu-snippets/examples/sixty-seconds.rsis the program the README prints, andcrates/zu-snippets/tests/readme.rsholds the page to it character for character and then runs it. Both halves matter and the second is the one with teeth: compiling proves the names still exist, running proves the statements in it still parse, the file it writes still opens, and the two lines the page claims it prints are the two lines it prints. It runs in a temporary directory, because a reader runs it in the directory they are standing in and findssocial.zu1beside them afterwards.The package is a package because a crate cannot depend on itself under a second name, and the snippet has to say
zudb: that is what a reader types aftercargo add zudb, and it is not what this crate is called in this workspace. So the snippets live one level out, depend onzudb = { package = "zu", path = "../zu" }, and read exactly as a reader's file does.The README gains a
## Sixty secondssection holding the program, a sentence on whycreateis notopen, and a pointer to the same sixty seconds in Python.crates/zu/benches/convert.rsis reformatted, which is nothing to do with any of this and is whatcargo fmt --all --checkwants on main today.Local:
make lint,make test,cargo xtask terms,api-mapandreposall green.