project.yaml
A project is a directory under ~/.local-review/projects/, and project.yaml in it says which repos and commits the
project covers and how they split into PR stacks. local-review init <slug> creates one from
examples/project.example.yaml,
a commented starting point. Edits are picked up live.
Example
Section titled “Example”title: My feature# optional: the project intro (markdown), one or two paragraphs of context; every full PR body starts with itdescription: | Why this effort exists, …repos: - name: my-service # optional, default: the path's basename; used in URLs and dir names # (a duplicate gets "-2", "-3"… by position, with a warning: name it) path: ~/code/my-service branch: me/my-feature # range end = branch head (or `to: <sha|ref>`, inclusive); optional with `landed:` base: origin/main # range start = merge-base(base, end), exclusive; default origin/HEAD, main, master # from: <sha|ref> # alternative start: the first commit included (overrides base) # landed: ["0a1b2c3d", …] # optional: merged PRs, bottom to top: keys of prs/<repo>/<sha>.yaml files # github_stack: 12 # optional, informational: the GitHub stack these PRs went up as stacks: # optional; consecutive groups, in order - title: Groundwork color: blue # blue green purple orange pink teal red, or "#hex"; default cycles (no yellow) starts_at: "Add the config loader" # optional: a stack note (markdown), inter-stack context; after the intro in this stack's full PR bodies description: | First of three stacks: … - title: The feature itself starts_at: "Add the feature flag" - title: Later starts_at: "Polish the feature" follow_on: true # optional: parked work, held back from the stacks going up nowTop level
Section titled “Top level”| Field | ||
|---|---|---|
title | string | The project’s name in the header, the project switcher, the sidebar, the root page and the project page. Default: the slug. |
description | markdown, optional | The project intro: context for the whole effort. Shown on the project page and in the Project context box of each stack and PR page, and first in every full PR body. Editable in the UI; can show images. |
repos | list | One entry per repo, below. |
after | slug, optional | The project this one builds on (linked projects): another project’s slug. In a repo both have, this project’s range starts where that one’s ends, while that’s an ancestor of this branch. Matched by path, else by repo name; a repo with from: ignores the link. No such project, this project itself, a cycle or a value that isn’t a slug is a warning, and no link. |
hidden | boolean, optional | true keeps the project off the root page (its cards and section counts) and out of the project switcher, without deleting or moving anything: for a parked experiment, or a demo of a chain of linked projects that leaves the last one out. Its URL still opens it (and the switcher lists it while it’s open), and after: links to and from it still hold, so no range changes. Default false. |
github | {sync: off}, optional | Leaves this project’s PRs out of GitHub status: they’re never fetched from GitHub, by the server or by local-review github refresh. {sync: on} or absent: they take part whenever the sync is on (config.yaml). Anything else is a warning, and ignored. |
example | boolean, optional | Marks one of the example projects: the UI labels it Example and offers to remove it. Set by local-review examples; you don’t need it. |
The project’s slug is its directory name (not a field): it’s used in URLs, /<slug>/<repo>/<sha>.
repos[]
Section titled “repos[]”| Field | ||
|---|---|---|
path | path | A local clone, required: an entry without one is skipped, with a project warning. ~ is expanded. It is only ever read, never modified (read-only guarantee). |
name | optional | Used in URLs and as the directory name under prs/ and reviews/. Default: the path’s basename. Two repos with the same name get -2, -3, … by position, with a warning: name them. Letters, digits, ., _, -: any other character becomes -, and a leading dot _. |
branch | ref | The range end: this branch’s head. Optional once the repo has landed:. |
to | sha or ref | Instead of branch: the range end, inclusive. |
base | ref | The range start: merge-base(base, end), exclusive. Default: origin/HEAD, else main, else master. In a project with after:, a repo the predecessor also has starts at the predecessor’s range end instead while that’s an ancestor of end (linked projects). |
from | sha or ref | Instead of base: the first commit included. Overrides base. |
pr_model | follow-ups or commit, optional | follow-ups: commits on top of a PR’s branch, up to its head, are part of that PR, not PRs of their own. See Follow-up commits. Default (commit): every commit is a PR. |
landed | list, optional | The repo’s merged PRs, bottom to top: the keys (file names) of their prs/<repo>/<sha>.yaml files, a full sha or a unique prefix (quote prefixes). See Landed PRs. |
github_stack | number, optional | Informational: the GitHub stack these PRs went up as. |
stacks | list, optional | Consecutive groups of the range’s commits, in order, below. No stacks: means one stack named after the branch. |
Refs may only use letters, digits and . _ / @ { } ^ ~ + -, must not start with - and must not contain ..
(one that breaks this is reported as not found). Git is given them as data, on its standard input or after
--end-of-options, never as options.
stacks[]
Section titled “stacks[]”| Field | ||
|---|---|---|
title | string | The stack’s name (STACK 1 · GROUNDWORK in the sidebar), and part of its stack page’s URL. A stack can also be written as just - Title. Default: Stack n. |
starts_at | selector | The commit the stack starts at: a commit subject, a hex sha prefix (7+ characters; quote it), or a PR title. The first stack may leave it out. The rules. |
color | optional | blue, green, purple, orange, pink, teal, red, or a "#hex". Default: cycles through that list in order. yellow is reserved for follow-on stacks. Colours. |
description | markdown, optional | The stack note: how this stack relates to the others. Shown on the stack’s page and in the Stack context box of each of its PRs, and after the intro in its full PR bodies. Editable in the UI; can show images. |
follow_on | true/yes, optional | Marks the stack as parked work. false, no or absent: a regular stack. Any other value is ignored, with a warning. |
How the UI edits it
Section titled “How the UI edits it”The UI writes to project.yaml in exactly two places: the project intro and the stack notes (the description:
fields), when you edit them on the project or stack page, or in the Project context and Stack context boxes. It never writes anything you didn’t
type: no text is generated.
- Saving writes just that one field (as a
|block; saving it empty removes the key), through theyamlpackage’s Document API, so comments, key order and quoting elsewhere in the file are kept. Only the spacing before a trailing# commentis normalised to one space. - The write is atomic, re-reads the file just before writing and re-applies the change if it moved (an agent saved it), and is refused (HTTP 409) while the file doesn’t parse.
- A stack is addressed by its position in
stacks:, with its title as a guard, so a note never lands on a stack that was reordered meanwhile. A- Titleshorthand stack becomes- title: Titleto hold one.
Errors and warnings
Section titled “Errors and warnings”Problems show on the repo in the sidebar:
- Project errors (the project can’t be read; ⚠ on its card): invalid YAML, a top level that isn’t a mapping, or
repos:that isn’t a list. - Errors (an error card): a missing repo, a missing branch, or a range that can’t be worked out (no
branchorto, ato,fromorbasethat doesn’t exist, afromthat isn’t an ancestor of the end, no common ancestor), or abranch,to,fromorbasewith characters Local Review won’t pass to git (it allows letters, digits and. _ / @ { } ^ ~ + -, not a leading-or..). A missing branch isn’t an error in a repo with landed PRs; there, other range problems are only warnings. - Project warnings (on the project page, at the top of the sidebar and in
local-review plan): a badafter:(not a slug, no such project, the project itself, a cycle), and an entry inrepos:that’s skipped because it has nopathor isn’t a mapping. - Warnings: a range that includes the commits of the project it builds on, or whose predecessor’s branch is gone
(when the link doesn’t hold); a
starts_atthat matches nothing, or matches only commits at or before the previous stack’s start (that stack is then empty); a later stack with nostarts_at(also empty); an unknown colour;color: yellowon a regular stack; a regular stack after a follow-on one; an invalidfollow_onvalue;stacks:orlanded:that isn’t a list; duplicate repo names;landed:keys that match no prs file, several, or one without a usablelanded:block, and duplicates.