Core concepts

A short tour of the ideas that make the rest of the guide click.

The git-native round-trip

TheoWorks does not store your work in a database. Your project is the RST files in your Git repository. When you edit a need, TheoWorks parses the RST, applies your change, and writes it back — producing a minimal, clean diff. Because the source is plain text in Git, you keep code review, history, branching, and offline copies. TheoWorks is the editor; Git is the store.

Why it matters: you are never locked in. If you stop using TheoWorks tomorrow, you still have a valid sphinx-needs project that builds with plain Sphinx.

Round-trips are byte-stable: editing one need and saving does not reflow or reformat the parts of the file you did not touch.

Needs: typed and traceable

A need is a single tracked item — a requirement, an architecture element, a test case, or a documentation block. Every need has a type (which controls its allowed fields, links, and colour), a stable id, a status, and any custom fields your schema defines. Needs connect to each other through typed links (for example satisfies, refines, verifies), and those links form the traceability graph.

The editor renders that graph: pick a need to see its fields and its outgoing links, with dangling (missing) targets flagged.

Validation and workflows

Your project's metamodel (schema) declares, per need type, which fields and links are required and which status transitions are legal (for example draft → review → published). TheoWorks checks needs against this schema and reports findings — a missing required link, an illegal status — so problems surface while you edit rather than at build time. A CI build can gate on the same rules.

Provenance: authored vs. generated

Not every need is hand-authored. Some are generated or imported by other tooling during the build. TheoWorks tracks this provenance: authored needs are editable, while generated/imported needs are shown read-only. This "do-no-harm" rule means TheoWorks never corrupts or overwrites content it did not author.

The change lifecycle

A change moves through distinct stages:

Saved → Committed → Pushed → Built → Active

• Saved — written to the working file.
• Committed — recorded in Git history.
• Pushed — shared to the remote.
• Built — validated/rendered by CI.
• Active — merged.

This is the concept most likely to trip you up: if you save an edit but validation or the rendered graph hasn't updated, it's usually because the change has not yet been built. See Using the editor for where each of these lives in the UI.

Next, decide how to run it: Choose your flavor.