From d20ef224268368e35a6abdae08e553aca36df743 Mon Sep 17 00:00:00 2001 From: finalerock44 <77282157+finalerock44@users.noreply.github.com> Date: Tue, 18 Aug 2026 13:01:43 +0100 Subject: [PATCH] chore: promote the #124 docs into 5.3.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Promote from dev to stable, carrying the documentation half of #124 that the 5.3.1 promotions dropped. `ci: stop reaching into the private dcd repo for the mock-api` (#124) touched six files on dev. The promote PR (#123) carried four of them — `cli-ci.yml`, `scripts/test-runner.mjs`, the `test:unit` script in `package.json`, and eight of the ten changed `CLAUDE.md` lines — and dropped `CONTRIBUTING.md` and `README.md` entirely. Production therefore ships the new CI shape while its docs still describe the old one: * `CONTRIBUTING.md` told contributors `pnpm test` boots a mock API, and that integration tests are "automatically skipped" on fork PRs only. Neither is true: CI runs no integration tests on any PR, and there is no default mock. It also omitted `pnpm test:unit` from the pre-push checklist, though it is now a required check. * `README.md`'s dev-scripts block still showed `pnpm test # build + boot mock API + integration/unit tests`. * `CLAUDE.md`'s Contributing section still described the `DCD_SSH_DEPLOY_KEY` mock-api checkout, which no longer exists. `README.md` is the one with reach beyond this repo: npm always includes it in the tarball regardless of the `files` field, so the stale snippet would render on the npmjs.com page for 5.3.1. Docs only — no source, workflow, script or lockfile change. The three files are now byte-identical to `dev`, leaving release plumbing (both manifests, `CHANGELOG.md`, `package.json` version) as the only remaining divergence, which is release-please's to own. `Release-As: 5.3.1` keeps the pending release PR (#120) on 5.3.1 rather than rolling it to 5.3.2. Release-As: 5.3.1 --- CLAUDE.md | 2 +- CONTRIBUTING.md | 28 +++++++++++++++++++--------- README.md | 3 ++- 3 files changed, 22 insertions(+), 11 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 58428d3..a9bf70d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -61,7 +61,7 @@ Full guide in `CONTRIBUTING.md`; the operationally important parts (the ones tha - ⚠️ **A `!` (or `BREAKING CHANGE:` footer) bumps the MAJOR — do not use it casually.** The configs set `bump-minor-pre-major: true`, but that only applies **below 1.0.0**; we are on 5.x, so it is inert and a breaking marker means exactly what semver says. A `refactor(cloud)!:` PR title once produced a `6.0.0-beta.1` release PR for what was only a flag rename in an unconsumed beta. Because PRs are squash-merged, **the PR title IS the commit** — the `!` lands even if no branch commit carried it. - **Never hand-edit `package.json` version, `CHANGELOG.md`, or the `.release-please-manifest*.json` files** — release-please owns all of them. `src/types/generated/schema.types.ts` is likewise generated (openapi-typescript). - A first-time contributor must sign the CLA (the CLA Assistant bot comments on the first PR); the CLA check must be green to merge. -- **CI (`.github/workflows/cli-ci.yml`) runs on every PR** including forks: gitleaks secret scan, `pnpm lint`, `pnpm typecheck`, `pnpm build`, `pnpm audit --audit-level moderate`. The **integration tests need the private `devicecloud-dev/dcd` mock-api** (cloned via the `DCD_SSH_DEPLOY_KEY` secret), and GitHub withholds secrets from fork and Dependabot PRs — so `pnpm test` is **skipped there** and a maintainer runs the full suite before merge. gitleaks also runs as a pre-commit hook (allowlist in `.gitleaks.toml`); without the binary installed the hook self-skips and CI is the backstop. +- **CI (`.github/workflows/cli-ci.yml`) runs the same steps on every PR** — fork, Dependabot and same-repo alike, with no privileged path: gitleaks secret scan, `pnpm lint`, `pnpm typecheck`, `pnpm test:unit`, `pnpm build`, `pnpm audit --audit-level moderate`. **`test/integration/*` is not run by CI at all** (see the Commands section: this public repo no longer reaches into the private `devicecloud-dev/dcd` repo for a mock API), so a green PR says nothing about the integration suite — run it locally with `MOCK_API_DIR` set if a change touches the API surface. gitleaks also runs as a pre-commit hook (allowlist in `.gitleaks.toml`); without the binary installed the hook self-skips and CI is the backstop. ## Releases diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1761173..1560eac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,19 +37,29 @@ Useful scripts: | `pnpm lint` | ESLint over `src/` and `test/` | | `pnpm typecheck` | Strict `tsc --noEmit` over `src/` and `test/` | | `pnpm build` | Compile to `dist/` | -| `pnpm test` | Build + boot the mock API + run integration/unit tests | +| `pnpm test:unit` | Run the unit suite — no backend needed. **This is what CI runs.** | +| `pnpm test` | The same, plus the integration suite if `MOCK_API_DIR` points at a mock API | -**Before pushing, make sure `pnpm lint`, `pnpm typecheck`, and `pnpm build` -pass.** These run for every PR (including from forks) and are required to merge. +**Before pushing, make sure `pnpm lint`, `pnpm typecheck`, `pnpm test:unit`, and +`pnpm build` pass.** These run for every PR and are required to merge. ### About the test suite -`pnpm test` boots a **mock API that lives in a private repository**, so the full -integration suite only runs on branches inside this repo. **On pull requests from -forks the integration tests are automatically skipped** — you'll see a CI notice -saying so. That's expected: lint, typecheck, and build still run and gate your -PR, and a maintainer runs the full suite before merge. You don't need backend -access to contribute. +Tests split in two. `test/unit/*` is pure — no network, no backend — and runs +everywhere, in CI and locally. + +`test/integration/*` drives the built CLI against a Prism mock of the dcd API on +port 3001. **CI does not run it**, on any PR, from a fork or otherwise: this repo +is public and deliberately holds no credentials for, and makes no requests to, +our private infrastructure. There is no default mock API — set +`MOCK_API_DIR=/path/to/mock-api` (a package exposing a `start:auth` script on +port 3001) and `pnpm test` picks the integration suite up. Without it the runner +prints a notice and runs the unit suite alone. + +So every contributor, maintainers included, gets the same CI signal, and you +don't need backend access to contribute. The flip side is worth knowing: a green +PR says nothing about the integration suite, so if your change touches the API +surface, say so in the PR and a maintainer will exercise it before merge. ### Secret scanning diff --git a/README.md b/README.md index f0da192..fdb4804 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,8 @@ $ pnpm install # install deps, build, set up git hooks $ pnpm dcd # run the CLI from source $ pnpm lint # ESLint $ pnpm typecheck # strict tsc, no emit -$ pnpm test # build + boot mock API + integration/unit tests +$ pnpm test:unit # unit tests, no backend needed — what CI runs +$ pnpm test # the above, plus integration tests if MOCK_API_DIR is set ``` ### Secret scanning