circagraph
Sign inSign up

openchronology/timeline-app on GitHub

The OpenChronology repository on GitHub, mirrored by och-import-github: issues and pull requests as durations (ongoing while open), what happened to them as moments, plus releases, milestones, commits and branches. The Branches view shows the most recently active branches each in a track of its own.

Source: https://github.com/openchronology/timeline-app

3,131 moments · 2026-10-05 CE 20:21:49 UTC – 2026-11-16 CE 12:10:45 UTC · by @athan · @athan

#192 Richer comments, the SQL first (#177)

–

  • github
  • github/openchronology/timeline-app
  • github/openchronology/timeline-app#192
  • pull request
  • state:merged

Closes #177. Comments only: about 6,000 lines across 80 files, focused on the SQL as asked. Eight agents wrote them in parallel, each on one area, to shared rules: say why, not just what; be accurate; correct stale comments; change no code. ## The SQL - **`server/schema.sql`:** - **Header:** how `migrate.mjs` runs the file and why every statement can be run again. - **Tables and columns:** what each of the 58 tables stores and which modules read and write it, plus its non-obvious columns. - **Indexes:** the query each one serves, and why partial ones are partial. - **Functions:** each has a header covering purpose, arguments, result, algorithm, locking and cost, with step comments inside its body. That includes the functions generated from others: the versioned triggers, the `_at` readers and the `_lineage` walks. - **Upgrades:** each idempotent upgrade statement says what changed and why it's safe to run again. - **Generated copies:** some functions are generated by rewriting other functions' text, so no comment inside those bodies contains a string the rewriting searches for. A note above `oc_rewrite` warns future editors. - **SQL in the server:** `store.mjs`, the versioned index and history (`history`, `index-versions`, `incremental`, `avl`, `merge`, `versioning`…), accounts and security, moderation, administration, collaboration, standing, retention, plugins, the log receivers, and the request router. - **Each non-trivial query** says what it reads or changes and why: locks (`FOR UPDATE`, `SKIP LOCKED`, advisory locks), isolation levels, CTEs and recursive CTEs, `ON CONFLICT`, `RETURNING`, keyset paging, and the indexes it relies on. - **Functions:** every function has JSDoc. - **`http.mjs`:** says, for each route group, who may call it and what's checked first. - **SQLite in the desktop app (`native-store`):** the file format, every table and index, and the save transactions and viewport queries. `src-tauri` documents each native command. ## Elsewhere The editor modules and website components with the fewest comments now have JSDoc for every function and component, and notes on their non-obvious logic. ## Corrections - **Wrong or stale comments fixed:** for example, history no longer "writes a full snapshot periodically"; `durationDefinitions` skips legacy rows rather than converting them; a moderation comment claimed at most one case per target; a plugin lock was said to enforce the quota. - **References updated:** comments naming functions that no longer exist now name the current ones. - **Comments moved to the right function:** in `store.mjs`, `workspace.rs` and `hover-preview.ts`. ## How it was checked - **Code unchanged:** a script compared every changed file with `main` token by token, ignoring comments (and `--` lines inside SQL strings). All 80 are unchanged apart from comments. - **Schema checked in a real database:** the schema was loaded into a brand-new database twice. Every function (203, generated ones included), table (58) and index (133) it creates was compared with `main`'s, and they are identical apart from comments. - **Tests pass:** - 289 unit tests, typecheck and Prettier; - `cargo fmt --check`, and both crates' tests; - the 45-test database suite, plus the main database tests on that fresh database; - the 11 browser suites; - the offline edition's test. ## Bugs the agents found I'm not fixing code in this PR. The five I've confirmed are fixed in a separate PR; the rest are filed as an issue. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_011fFY8eruEi1xAkkMBni13B https://github.com/openchronology/timeline-app/pull/192

Related

Open #192 Richer comments, the SQL first (#177) in the timeline

#192 Richer comments, the SQL first (#177)