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

#191 A map of the repository: a README in every folder, a synopsis in every file (#176)

–

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

Closes #176. ## What's added - **A README.md in every folder** (85 of them). Each says what the folder is for and how it fits in, and has a **Contents** table: one row per file and subfolder, saying what it's for, with links to the subfolders' READMEs. - **Every folder:** this covers each of the website's Next.js route folders, which say the address they serve and where their logic lives. - **Kept as they were:** the packaging READMEs already in `deploy/` (README.Debian, README.RPM and so on) are listed alongside. - **Left out:** vendored projects keep their own documentation; `vendor/README.md` lists them. There is no `.github/README.md`, because GitHub would show it in place of the repository's front page; `.github/workflows/README.md` covers the workflows. - **`CONTRIBUTING.md`, the top level's table of contents**, as the issue asks. It covers every top-level file and folder, how to find your way (folder READMEs, synopses, `docs/` and `/help`), and how to make a change. The README links to it. - **A synopsis at the top of every code file:** after the copyright line, a comment of a line or a few saying what the file is for. About 240 files gained one: those without any, and those whose only early comment described a single function rather than the file. - **Comments only:** the diff changes no code, only comments, apart from the follow-ups below. ## Keeping it right `test/contents.test.mjs`, part of `npm test`, fails when: - a folder has no README, or no Contents table; - a README leaves out a file or subfolder, lists one that isn't there, or leaves an entry undescribed; - a link in a README leads to no file, or to a heading a doc doesn't have; - a code file has no synopsis in its first lines (lockfiles and vendored code excepted). ## Follow-ups found along the way - **The help area** leaves out `docs/README.md`, which is for people reading the repository. The help has its own index, and "readme" there is the project's README. - **Server packages:** the .deb, the .rpm and the platform archive (FreeBSD, Homebrew, Windows) copy the project's README and then `docs/` into the same doc folder. They would have installed `docs/README.md` over the project's README, so the docs are now copied first. The new `deploy/homebrew/README.md` is left out of the archive like `tap-README.md`. - **Copyright lines:** four files had theirs below their imports (`src/core.ts`, `src/app.ts`, `test/browser.mjs`, `test/offline-browser.mjs`); it's back on the first line. - **A wrong comment:** `deploy/debian-server/Dockerfile` named `scripts/server-deb.mjs`, which doesn't exist; it now names `scripts/server-package.mjs`. ## Noticed, not changed - **Possibly unused:** `deploy/plugins.example.json` isn't referenced anywhere. - **Redundant under Next:** both `platform/app/api/openapi.json/route.js` and a branch in `server/http.mjs` serve the OpenAPI document. Under Next only the route file is reached. The `http.mjs` branch is what the plain Node server uses. ## Tests Locally, all of the following pass: - 289 unit tests, including the new contents tests; - typecheck and Prettier; - `cargo fmt --check`, and both crates' tests; - the 45-test database suite; - the 11 browser suites; - the offline edition's test. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_011fFY8eruEi1xAkkMBni13B https://github.com/openchronology/timeline-app/pull/191

Related

Open #191 A map of the repository: a README in every folder, a synopsis in every file (#176) in the timeline

#191 A map of the repository: a README in every folder, a…