timescale.info#191 · A map of the repository: a README in every folder, a synopsis in every file (#176)
- timeline-app
- pull request
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.