docs(onboarding): rewrite as a complete new-repo fleet runbook - #69
Merged
Conversation
ONBOARDING.md: full path from repo creation to fleet membership — repo creation with branch auto-delete, package.json baseline (engines, gate scripts), toolchain install (prettier/eslint packages with entry-point choice), sync group selection, deploy key, Protect main ruleset recipe (7 contexts, DeployKey bypass), Snyk import, Renovate selection, CI_SKIP variables, npm trusted publishing, verification PR. Existing-repo pre-flight retained as Path B. README: seven stubs (ci.yml merge gate was missing from the checks table), group table includes the config packages, repo-local automation in layout. linting-and-formatting: fleet packages replace the per-repo-config and 80-column narratives; gate table includes format + Snyk. config-single-source-of-truth: fleet count and prettier-key consumers.
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
There was a problem hiding this comment.
Pull request overview
Updates fleet documentation to provide an end-to-end “new repo → full fleet member” runbook and align formatting/linting guidance with the current shared-config model.
Changes:
- Rewrites ONBOARDING.md into a structured Path A/Path B onboarding runbook (repo creation → tooling → sync → rulesets → Snyk/Renovate → verification).
- Refreshes README.md to reflect the current workflow set (7 reusables / 7 stubs) and sync-group nuances (including
shared-ci.ymlcollisions). - Updates formatting/linting and config SSoT docs to describe consumption via
@nswds/*config packages and current gate behavior.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| README.md | Updates repo layout + sync-group table and enumerates the seven shared CI stubs (including ci.yml as the merge gate). |
| ONBOARDING.md | Complete onboarding runbook (new repo + existing repo pre-flight), including sync groups, ruleset recipe, and verification checklist. |
| docs/config-single-source-of-truth.md | Corrects fleet sizing and updates the “base-only” Prettier consumer list to include the config package repos. |
| docs/best-practices/linting-and-formatting.md | Reframes lint/format guidance around gates + centralized @nswds/* configs and updates the narrative for current enforcement. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+68
to
+71
| and a real `"test"` script if the repo has a suite. The shared CI jobs run | ||
| `lint`/`test` with `--if-present` and the format job only runs when a | ||
| Prettier config exists — a missing script means a silently green gate, so | ||
| wire up every one the repo can honestly run. |
Comment on lines
+253
to
+257
| Import the repo into the `digitalnsw` Snyk organisation (Snyk console → Add | ||
| project → GitHub). Snyk then posts three commit statuses on every PR head — | ||
| `code/snyk`, `security/snyk`, `license/snyk (DigitalNSW)` — and retests | ||
| `main` against new advisories between PRs. The fleet requires `security` and | ||
| `code` as merge gates; `license` stays advisory. |
| | prettier | Formatting | Per-repo config; see constraint below | | ||
| | eslint | JS/TS source | `install / lint` (required check; runs `npm run lint --if-present`) | | ||
| | prettier | Formatting | `install / format` (required check; runs `prettier --check .` when the repo has a Prettier config) | | ||
| | Snyk | Dependencies + code | `security/snyk` and `code/snyk (DigitalNSW)` (required checks; posted by the Snyk console integration) | |
Comment on lines
+236
to
+240
| {"context": "install / lint"}, | ||
| {"context": "install / test"}, | ||
| {"context": "install / format"}, | ||
| {"context": "security/snyk (DigitalNSW)"}, | ||
| {"context": "code/snyk (DigitalNSW)"} |
Comment on lines
+248
to
+249
| Bypass policy: **DeployKey only** — no admin or role bypass actors (the | ||
| rationale is in MAINTENANCE.md's bypass policy section). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Brings the operating docs to current state and answers "I have a brand-new repo/local folder — what are all the steps to full fleet membership?" end to end.
ONBOARDING.md — rewritten as a two-path runbook. Path A (brand-new repo): create with branch auto-delete on merge, package.json baseline (fleet engines range, gate + helper scripts), toolchain install with the ESLint entry-point decision (
.vs./base) and both Prettier consumption shapes, prettierignore policy, sync group selection with the group rules, deploy-key setup, "Protect main" ruleset recipe (all 7 required contexts incl. format + the two Snyk gates, strict, DeployKey-only bypass, with the require-only-what-posts rule), Snyk console import, Renovate app selection, CI_SKIP variables, npm trusted publishing for publishers, and a verification PR listing the exact expected checks. Path B: the existing-repo pre-flight (lockfile, stale ruleset names, bespoke release, superseded tooling).README.md — the shared-checks table now includes the
ci.ymlmerge gate (it listed six stubs and omitted the most important one), group table includes the config packages, layout shows promote-v1/drift-canary.linting-and-formatting.md — replaced the per-repo
.prettierrchouse-style and 80-column-constraint narratives with the current model:@nswds/prettier-config+@nswds/eslint-configpackages, the format/Snyk gates, and the prettierignore policy.config-single-source-of-truth.md — fleet count and prettier-key consumer list corrected.