From 596414319126727f4f216b90bf72e0ccaa2afb2d Mon Sep 17 00:00:00 2001 From: Jeff <138259519+jdotc1@users.noreply.github.com> Date: Fri, 6 Nov 2026 04:10:42 -0500 Subject: [PATCH] docs: describe CI checks and PR licence summary accurately --- CONTRIBUTING.md | 2 +- README.md | 6 +++++- site/README.md | 5 ++++- 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd5e3dd..ecf93c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,7 +37,7 @@ The website rebuilds from frontmatter on deploy. Node 22 or newer is all you nee 3. Write the body: a one-paragraph summary, `## Notes`, `## Evidence` with a dated line quoting the source, such as `- Live page (2026-09-25): "Free for commercial use"`, and optionally `## Related` linking sibling entries. Every Evidence section needs at least one date, and `verified` may not be newer than the newest one. The template (and so the scaffold) starts at `status: needs-review`; set `active` once the licence, the commercial stance and the credit requirement are all settled. 4. Add a row to the matching category `README.md`. This is required: the validator fails an entry that is not listed there, and the row's licence cell must match your frontmatter. 5. Run `node site/sync-counts.mjs` (`npm run counts`). It updates every place the repo restates the entry count: both category count tables, the README badge and "Browse N sources" line, and `expectedEntryCount` in [`site/config.json`](site/config.json). -6. Run `npm test && npm run validate` before you push; that is quick. CI then runs `npm run check` (the tests, `node site/validate.mjs` and `node site/build.mjs`), and all of it must pass. Run `npm run check` yourself if you changed the site or want to preview your entry's page. The build renders your entry's page and fails if the body uses markdown the site does not support (tables, code fences, blockquotes, images, raw HTML, `###` headings, numbered lists) or links to a file that does not exist. +6. Run `npm test && npm run validate` before you push; that is quick. CI runs the equivalent of `npm run check`: the tests, `node site/validate.mjs`, `node site/check-added.mjs` (with full git history to check added dates) and `node site/build.mjs`. On pull requests, CI also runs `site/pr-diff.mjs` to summarise changed licence fields beside their evidence; this is not part of `npm run check`. Run `npm run check` yourself if you changed the site or want to preview your entry's page. The build renders your entry's page and fails if the body uses markdown the site does not support (tables, code fences, blockquotes, images, raw HTML, `###` headings, numbered lists) or links to a file that does not exist. 7. Save files with LF line endings. `.editorconfig` and `.gitattributes` take care of it in most editors; the validator rejects a file that still contains a CR. 8. Optional: add the `id` to `site/config.json` → `featured` to pin it under Safe starting points. diff --git a/README.md b/README.md index c1920a4..77b8d6c 100644 --- a/README.md +++ b/README.md @@ -359,13 +359,17 @@ Please follow the [Code of Conduct](CODE_OF_CONDUCT.md). Node 22 or newer (CI and `.nvmrc` use 24); there is nothing to install. ```bash -npm run check # all of the below, in the order CI runs them +npm run check # tests, validate, check-added, build (in this order) npm test # the checks against known-bad fixtures, and the site modules' tests npm run validate # the catalog, against the checks (node site/validate.mjs) +npm run check-added # checks added dates against git history (requires full history) npm run build # builds the site into site/dist (node site/build.mjs) npm run serve # preview at http://127.0.0.1:3000 (node site/serve.mjs, no download) ``` +Pull-request CI also runs `site/pr-diff.mjs` to summarise changed licence fields +alongside their evidence. That PR-only step is separate from `npm run check`. +
diff --git a/site/README.md b/site/README.md index 6591491..b84b288 100644 --- a/site/README.md +++ b/site/README.md @@ -193,11 +193,14 @@ Retake it when the hero changes. ## Commands ```bash -npm run check # tests, validate, build: what CI runs +npm run check # tests, validate, check-added (git history), build npm run serve # preview site/dist npm run links # the link check, printed to the terminal npm run thumbs # fetch and resize the previews that are due (needs ffmpeg or magick) ``` +On pull requests, CI also summarises changed licence fields with +`site/pr-diff.mjs`; this extra step is not part of `npm run check`. + Deploy: `.github/workflows/pages.yml` (source = GitHub Actions), which first runs `ci.yml` as a reusable workflow.