Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 32 additions & 6 deletions docs/brief.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,38 @@ rally's projects, with every list bounded and every note cut short (well under 2
8. **More:** counts of what's outside the rally or past the bounds, with the command that lists each.
9. **Builds** (RAL-167): what's live, by the service's own word (`/v1/whoami`'s commit, or "older than RAL-156:
the service doesn't say its commit"); this CLI's commit; main's tip; and what's merged but not live, from
GitHub's compare of live and main: how many commits, each story named in their messages with the age of its
oldest commit, the count, and how long the oldest has waited ("13 stories merged, not live; the oldest for 6 h").
GitHub's compare lists at most 250 commits, so a service further behind than that reads short, and
`reads_short` says so with both numbers. When this CLI is ahead of the service, a hint says a build looks staged
and waiting on a restart: a hint, not a fact. All of it is observed from its own source. Nothing reads the lamplighter's rollout files. It needs `gh`
signed in, as the digest does, and says so when a read fails.
GitHub's compare of live and main: how many commits, and each story named in their messages with the age of its
oldest commit. GitHub's compare lists at most 250 commits, so a service further behind than that reads short, and
`reads_short` says so with both numbers. All of it is observed from its own source. Nothing reads the
lamplighter's rollout files. It needs `gh` signed in, as the digest does, and says so when a read fails.

The service, the viewer and the CLI are one binary, so a story merged after the service's build isn't thereby
waiting on the service (RAL-195, after the brief read "8 stories merged, not live" of commits that changed
only the CLI, the viewer, docs and tests). What's read is every commit on main's own line (its first-parent
chain) since the service's build: a pull request's merge, or a commit made straight on main. GitHub lists a
merge's files against its first parent, so these commits' files together are exactly what changed on main, each
change once. A pull request's commits are covered by its merge whatever their messages say ("address review"
as much as "RAL-148: ..."), and a merge of main into a branch, which repeats what main already had, isn't read.
Each commit's files go to the stories it names or brought to main; one that names and brought none is listed by
its commit in `unnamed` when it may wait on the service, and counted with the stories ("1 story and 1 commit
naming no story merged, not live on the service"). Each says what it `waits_on`:
- `service`: a file the service runs changed (`builds::SERVICE_MODULES`, or `Cargo.toml`, `Cargo.lock`,
`build.rs`), listed in `service_files`. Only these are counted: "2 stories merged, not live on the service;
the oldest for 6 h", and `count` and `oldest_age_ms` are theirs.
- `can't tell`: only files the service shares changed, listed in `shared_files`: `src/main.rs` (every
command, `serve` among them), `src/web.rs` (the viewer, and the roadmap parser the service uses) and
`src/lib.rs` unless its patch only names modules the service doesn't run; or a commit's files couldn't be
read. Read the diff. It's never counted as live.
- `cli or viewer`: only code the CLI or the viewer runs changed. It's live wherever those are on a build that
has it: `cli_build` says this CLI's commit, how far behind main it is and which stories it `lacks`, and
`viewer_build` the build of the viewer `rally view` started on this machine, from its run file.
- `nothing running`: docs and tests only.

Past 60 commits landed on main, or when GitHub lists fewer commits than the service is behind, the files
aren't read: `files_unread` says so, and every story counts as before.
When this CLI is ahead of the service and a story or commit waits on the service or can't be told, a hint says a build
looks staged and waiting on a restart: a hint, not a fact. A new file in `src/` must be placed in one of the
lists in `src/builds.rs`, which a test checks; one this CLI's build doesn't know reads as `can't tell`.
10. **In flight** (RAL-191): the jobs a closed window would end (issues log 1.73, when every session's background
jobs ended with the shell windows and nothing said what had been running). For each project's `stalls.locks`
in the projects list beside the pairing, every held lock: its holder's pid, state, command line and working
Expand Down
9 changes: 9 additions & 0 deletions docs/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -1521,3 +1521,12 @@ principles named were durable, accurate and reactive. Found in rally 0x7 by plus
spot naming how many processes' open files couldn't be read, never "no holder"; the brief's `in_flight` shows
the same; with a test that the stopped and possibly-hung checks prompt for a holder found this way
(docs/stalls.md).
- [ ] **RAL-195: The brief's "merged, not live" counts only what the service runs.** From the watchman
(2026-11-15): `rally brief --watchman` read "8 stories merged, not live; the oldest for 32 h" (RAL-186 to 193)
because it compared main with the service's commit, when none of those commits changed what the service runs;
the watchman repeated the reading to the lamplighter and was wrong. Done when: a merged story counts as not
live on the service only when what it brought to main changes a file the service runs, from GitHub's files for
each commit on main's own line; a commit there that names no story is read too, and counts by its commit; a story that changes only files the service shares (`src/main.rs`, `src/web.rs`) says it can't be
told and is never called live; the rest say they change only the CLI, the viewer, docs or tests, and the
section says which build this CLI and the viewer here are on; a test keeps every file in `src/` placed as the
service's, shared or the client's; with tests of each reading (docs/brief.md).
Loading
Loading