book: Guide, coming from Go and Python (slice of #588)

orion commented

2026-10-29 20:51:41 +00:00

Collaborator

Slice of #588 (Guide, coming from another language), which is a slice of the epic #582. First of three: this one starts the folder and writes the Go and Python pages; Rust with TypeScript and JavaScript, then Kotlin and Swift, follow just in time. Starts after #607 is merged (both change book/guide/index.md and regenerate the same skills). Governing note: book/CONCEPT.md ("How a page is written", "What CI checks"). Touches the seed: no (documentation only; no syntax change, no native, no driver flag, no std name looked up by the compiler).

Goal

Write book/guide/coming-from/index.md (kind index, the folder's overview, generated list via torb docs index book) and the two pages book/guide/coming-from/go.md and book/guide/coming-from/python.md. A reader who knows Go or Python gets, on one page, the three or four things they trip over first, each with a TorbScript example and its output. Read like book/guide/handling-errors.md (the merged vertical slice): prose first, headings name ideas.

Replaces in `docs/`

docs/guide/coming-from/go.md
docs/guide/coming-from/python.md

About 140 lines of old material. The old docs/guide/coming-from/index.md stays until the last slice; regenerate its list (torb docs index docs) so it no longer links the two deleted pages.

Acceptance criteria

book/guide/coming-from/index.md (kind index, status: stable, a first paragraph of two to four sentences saying who the chapter is for) and go.md, python.md (kind page, status: stable, title, summary, order, keywords) exist, written as book/CONCEPT.md, "How a page is written", says: first paragraph says what the page covers, headings name ideas, prose first, no history words, no internal references (no issue numbers, no links into docs/design, docs/contributing, docs/internals, CONCEPT.md), no Related/Next/See also sections, lists of at most seven items, every section starts with a sentence
Each page opens with the three or four things a programmer of that language trips over first (Go: nil and zero values, (value, error) against Result and ?, interfaces by accident against with, go and channels against tasks; Python: values against references and the copy on assignment, no None and no exceptions, indentation-free blocks and const/var, types that are checked before the program runs), each with a TorbScript example and its output
Every trb run and trb error block is followed by its output block with the real output (a trb error block shows what torb check prints, from error: on); no fragments, no // prints comments; the code of the other language is a plain go or python block that is not run
The signature features each language trips on are shown, not just named: "Values, not references" and "No null and no exceptions" on the Python page, "No null and no exceptions" and "Every case is handled" on the Go page
torb docs check book, torb docs index --check book and torb docs site book --check pass, book/guide/index.md lists the new folder (generated block), and tools/gates.sh passes in CI; the site builds the folder (the sidebar shows the chapter and its pages); if torb docs site does not yet handle a nested guide folder, the PR fixes the generator in a separate commit
The two old pages are deleted in the same PR unless a skill is still built from them. skills/torbscript is generated by torb docs skill docs skills and links them; for every old page a skill still needs, it stays in docs/ unpublished and the PR description names it and why; the others are deleted together with every link to them (docs/guide/index.md, docs/guide/tour.md, the old coming-from index), and the skills are regenerated so docs skill --check stays green
No other book page is changed except the generated index list and links that must follow from the deletion; Rust, TypeScript and JavaScript, Kotlin and Swift are not started

Notes for the implementer

Read book/CONCEPT.md, book/guide/handling-errors.md and the two old pages first; run the examples with torb before pasting their output. The old pages use // prints comments and a table; rewrite as prose and output blocks, do not copy the table. Drop "not built yet" statements (history words): say only what is true now, and leave out what the language does not have yet.
Commits: one or two Conventional Commits, for example docs(book): guide coming from Go and Python and, if needed, docs: retire the coming-from pages the book replaces.
Size: one PR, 30-40 minutes. Do not write other languages.

Slice of #588 (Guide, coming from another language), which is a slice of the epic #582. First of three: this one starts the folder and writes the Go and Python pages; Rust with TypeScript and JavaScript, then Kotlin and Swift, follow just in time. Starts after #607 is merged (both change `book/guide/index.md` and regenerate the same skills). Governing note: `book/CONCEPT.md` ("How a page is written", "What CI checks"). Touches the seed: no (documentation only; no syntax change, no native, no driver flag, no std name looked up by the compiler). ## Goal Write `book/guide/coming-from/index.md` (kind `index`, the folder's overview, generated list via `torb docs index book`) and the two pages `book/guide/coming-from/go.md` and `book/guide/coming-from/python.md`. A reader who knows Go or Python gets, on one page, the three or four things they trip over first, each with a TorbScript example and its output. Read like `book/guide/handling-errors.md` (the merged vertical slice): prose first, headings name ideas. ## Replaces in `docs/` - `docs/guide/coming-from/go.md` - `docs/guide/coming-from/python.md` About 140 lines of old material. The old `docs/guide/coming-from/index.md` stays until the last slice; regenerate its list (`torb docs index docs`) so it no longer links the two deleted pages. ## Acceptance criteria - [ ] `book/guide/coming-from/index.md` (kind `index`, `status: stable`, a first paragraph of two to four sentences saying who the chapter is for) and `go.md`, `python.md` (kind `page`, `status: stable`, `title`, `summary`, `order`, `keywords`) exist, written as `book/CONCEPT.md`, "How a page is written", says: first paragraph says what the page covers, headings name ideas, prose first, no history words, no internal references (no issue numbers, no links into `docs/design`, `docs/contributing`, `docs/internals`, `CONCEPT.md`), no Related/Next/See also sections, lists of at most seven items, every section starts with a sentence - [ ] Each page opens with the three or four things a programmer of that language trips over first (Go: `nil` and zero values, `(value, error)` against `Result` and `?`, interfaces by accident against `with`, `go` and channels against tasks; Python: values against references and the copy on assignment, no `None` and no exceptions, indentation-free blocks and `const`/`var`, types that are checked before the program runs), each with a TorbScript example and its output - [ ] Every `trb run` and `trb error` block is followed by its `output` block with the real output (a `trb error` block shows what `torb check` prints, from `error:` on); no fragments, no `// prints` comments; the code of the other language is a plain `go` or `python` block that is not run - [ ] The signature features each language trips on are shown, not just named: "Values, not references" and "No null and no exceptions" on the Python page, "No null and no exceptions" and "Every case is handled" on the Go page - [ ] `torb docs check book`, `torb docs index --check book` and `torb docs site book --check` pass, `book/guide/index.md` lists the new folder (generated block), and `tools/gates.sh` passes in CI; the site builds the folder (the sidebar shows the chapter and its pages); if `torb docs site` does not yet handle a nested guide folder, the PR fixes the generator in a separate commit - [ ] The two old pages are deleted in the same PR unless a skill is still built from them. `skills/torbscript` is generated by `torb docs skill docs skills` and links them; for every old page a skill still needs, it stays in `docs/` unpublished and the PR description names it and why; the others are deleted together with every link to them (`docs/guide/index.md`, `docs/guide/tour.md`, the old coming-from index), and the skills are regenerated so `docs skill --check` stays green - [ ] No other book page is changed except the generated index list and links that must follow from the deletion; Rust, TypeScript and JavaScript, Kotlin and Swift are not started ## Notes for the implementer - Read `book/CONCEPT.md`, `book/guide/handling-errors.md` and the two old pages first; run the examples with `torb` before pasting their output. The old pages use `// prints` comments and a table; rewrite as prose and `output` blocks, do not copy the table. Drop "not built yet" statements (history words): say only what is true now, and leave out what the language does not have yet. - Commits: one or two Conventional Commits, for example `docs(book): guide coming from Go and Python` and, if needed, `docs: retire the coming-from pages the book replaces`. - Size: one PR, 30-40 minutes. Do not write other languages.

orion added the

loop

ready

labels

2026-10-29 20:51:46 +00:00

orion added a new dependency

2026-10-29 20:51:47 +00:00

#607 book: Guide chapter first project (slice of #587)

orion added a new dependency

2026-10-29 20:51:47 +00:00

#588 book: Guide, coming from another language

orion referenced this issue

2026-10-29 20:51:55 +00:00

book: Guide, coming from another language #588

orion referenced this issue

2026-10-29 20:51:55 +00:00

book: Guide, coming from another language #588

orion commented

2026-10-29 23:04:54 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261030 until 2026-10-30T05:10Z

orion commented

2026-10-29 23:13:24 +00:00

Author

Collaborator

[loop:torbscript] checkpoint: go.md, python.md and coming-from/index.md written and every example run with a nightly torb; old docs pages deleted, indexes and skills regenerated. In flight: commit, push branch loop/608-coming-from-go-python, open PR. Next: forge CI.

orion referenced this issue from a pull request that will close it,

2026-10-29 23:13:37 +00:00

docs(book): guide coming from Go and Python #635

orion commented

2026-10-30 00:07:28 +00:00

Author

Collaborator

[loop:torbscript] release implement: the worker timed out after opening PR #635 (head e7e54344, CI pending, mergeable). The item is in review; CI and Argus decide.

[loop:torbscript] release implement: the worker timed out after opening PR #635 (head e7e54344, CI pending, mergeable). The item is in review; CI and Argus decide.

orion commented

2026-10-30 00:48:26 +00:00

Author

Collaborator

[loop:torbscript] wait until 2026-10-30T09:00Z: PR #635 (head e7e54344) is in review. Forge statuses gates and tier A show failure from run 2344, which the runs API lists as cancelled, so they look stale from CI congestion, not a real red; the job log is not readable (404). Needs a CI re-run or a fresh push before Argus can judge. No worker now.

[loop:torbscript] wait until 2026-10-30T09:00Z: PR #635 (head e7e54344) is in review. Forge statuses `gates` and `tier A` show failure from run 2344, which the runs API lists as cancelled, so they look stale from CI congestion, not a real red; the job log is not readable (404). Needs a CI re-run or a fresh push before Argus can judge. No worker now.