Skip to content

Commit b941510

Browse files
fergusbissetnhsfergusbissetnhs
committed
SPC Workflows
1 parent e8fb558 commit b941510

File tree

13 files changed

+477
-6
lines changed

13 files changed

+477
-6
lines changed

‎.github/workflows/spc-exports-snapshot.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: SPC Export Snapshot
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
branches: [ master ]
7+
paths:
8+
- 'packages/nhs-fdp-spc/**'
9+
- 'scripts/spc-export-snapshot.cjs'
10+
- 'package.json'
11+
12+
jobs:
13+
snapshot:
14+
runs-on: ubuntu-latest
15+
timeout-minutes: 10
16+
steps:
17+
- uses: actions/checkout@v4
18+
- name: Setup Node
19+
uses: actions/setup-node@v4
20+
with:
21+
node-version: 22
22+
cache: 'npm'
23+
- name: Install deps
24+
run: npm ci
25+
- name: Build SPC (types may be needed)
26+
run: npm run build:spc
27+
- name: Update export snapshot
28+
run: npm run spc:exports:snapshot
29+
- name: Commit snapshot if changed
30+
run: |
31+
git config user.name 'spc-bot'
32+
git config user.email '[email protected]'
33+
if ! git diff --quiet; then
34+
git add .
35+
git commit -m 'chore(spc): update export surface snapshot'
36+
git push
37+
fi
38+
- name: Summary
39+
run: echo '### Export snapshot updated (if changes detected).' >> $GITHUB_STEP_SUMMARY

‎.github/workflows/spc-parity.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: SPC Parity
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'packages/nhs-fdp-spc/**'
7+
- 'src/components/DataVisualisation/charts/SPC/**'
8+
- 'scripts/spc-parity-check.ts'
9+
- 'package.json'
10+
push:
11+
branches: [ master ]
12+
paths:
13+
- 'packages/nhs-fdp-spc/**'
14+
- 'src/components/DataVisualisation/charts/SPC/**'
15+
- 'scripts/spc-parity-check.ts'
16+
- 'package.json'
17+
18+
jobs:
19+
parity:
20+
runs-on: ubuntu-latest
21+
timeout-minutes: 10
22+
continue-on-error: true # Allow-fail initially; tighten later
23+
steps:
24+
- uses: actions/checkout@v4
25+
- name: Setup Node
26+
uses: actions/setup-node@v4
27+
with:
28+
node-version: 22
29+
cache: 'npm'
30+
- name: Install deps
31+
run: npm ci
32+
- name: Run SPC parity check
33+
run: npm run spc:parity
34+
- name: Publish parity summary
35+
run: |
36+
echo '### SPC Parity Check' >> $GITHUB_STEP_SUMMARY
37+
echo 'This job is allow-fail initially and will become required once fixtures are canonical.' >> $GITHUB_STEP_SUMMARY

‎.github/workflows/spc-validate.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: SPC Validate
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'packages/nhs-fdp-spc/**'
7+
- 'scripts/spc-*'
8+
- 'config/vite.spc.*'
9+
- 'package.json'
10+
push:
11+
branches: [ master ]
12+
paths:
13+
- 'packages/nhs-fdp-spc/**'
14+
- 'scripts/spc-*'
15+
- 'config/vite.spc.*'
16+
- 'package.json'
17+
18+
jobs:
19+
validate:
20+
runs-on: ubuntu-latest
21+
timeout-minutes: 15
22+
steps:
23+
- uses: actions/checkout@v4
24+
- name: Setup Node
25+
uses: actions/setup-node@v4
26+
with:
27+
node-version: 22
28+
cache: 'npm'
29+
- name: Install deps
30+
run: npm ci
31+
- name: Build SPC
32+
run: npm run build:spc
33+
- name: Validate SPC package
34+
run: npm run spc:validate
35+
- name: Export surface check
36+
run: npm run spc:exports:check || (echo '::error ::Export surface check failed' && exit 1)
37+
- name: Adoption metric (summary only)
38+
run: |
39+
npm run spc:adoption > adoption.txt || true
40+
echo '### SPC Adoption Metric' >> $GITHUB_STEP_SUMMARY
41+
sed 's/^/`/;s/$/`/' adoption.txt >> $GITHUB_STEP_SUMMARY || true
42+
- name: Bundle sizes summary
43+
run: |
44+
echo '### SPC Bundle Sizes (gzip approx)' >> $GITHUB_STEP_SUMMARY
45+
if [ -f packages/nhs-fdp-spc/dist/index.esm.js ]; then
46+
npx gzip-size-cli packages/nhs-fdp-spc/dist/index.esm.js >> $GITHUB_STEP_SUMMARY || true
47+
fi
48+
if [ -f packages/nhs-fdp-spc/dist/spc.css ]; then
49+
npx gzip-size-cli packages/nhs-fdp-spc/dist/spc.css >> $GITHUB_STEP_SUMMARY || true
50+
fi

‎CHANGELOG.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,30 @@ The format loosely follows [Keep a Changelog](https://keepachangelog.com/) and v
66

77
## Unreleased
88

9+
### Added (Unreleased – SPC Package Infrastructure)
10+
11+
- Internal SPC package `@nhs-fdp/spc` build & validation pipeline established (Vite lib + CSS build). New scripts: `build:spc`, `spc:validate`, `spc:exports:snapshot`, `spc:exports:check`, `spc:metrics`, `spc:parity`, and codemod helpers (`spc:codemod:*`).
12+
- Export surface governance added: snapshot + diff check prevents accidental removals prior to externalisation.
13+
- Bundle size gate (gzipped) introduced with initial budget ≤150KB (current `index.esm.js` ~52.15KB gzipped; `spc.css` ~3.00KB).
14+
- CSS artifact (`spc.css`) emitted with minimal styles; presence validated in `spc:validate` script.
15+
- SSR gate integrated into `spc:validate` ensuring SPC components remain server‑render safe.
16+
17+
### Changed (Unreleased – SPC Package Infrastructure)
18+
19+
- Standardised path alias usage: removed local `@ds` alias and rely solely on root alias `@/` for SPC barrels (simplifies future extraction and prevents duplicate resolution paths).
20+
- Deduplicated parity build steps (removed second redundant SPC CSS build invocation) to streamline build time.
21+
- Documentation updated (README draft) to reflect dual‑export adoption path and migration guide preview.
22+
23+
### Fixed (Unreleased – SPC Package Infrastructure)
24+
25+
- Resolved transient TypeScript declaration alias resolution warnings by eliminating the package‑local tsconfig path mapping; declarations now emit cleanly via root alias configuration.
26+
27+
### Notes (Unreleased – SPC Package Infrastructure)
28+
29+
- Current validation status: PASS (all gates green) after alias cleanup (10 Nov 2025).
30+
- Next extraction milestones will be tracked via conventional commit scopes (`feat(spc):`, `fix(spc):`).
31+
32+
933
## 0.0.40 - 2025-10-16
1034

1135
### Changed (FDP brand header)

‎config/vite.spc.config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ export default defineConfig({
2424
],
2525
resolve: {
2626
alias: {
27-
'@ds': resolve(__dirname, '../src')
27+
'@': resolve(__dirname, '../src')
2828
}
2929
},
3030
build: {

‎docs/engineering/spc-extraction-playbook.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# SPC Extraction Playbook (Shadow Repo ➜ Canonical)
2+
3+
End‑to‑end guidance for spinning up a shadow repository for `@nhs-fdp/spc`, validating it in parallel with the monorepo, and promoting it to the canonical source once readiness gates are met.
4+
5+
---
6+
7+
## 1. Objectives
8+
9+
| Goal | Why it matters |
10+
|------|----------------|
11+
| Isolate SPC release cadence | Ship SPC fixes/features without full design-system release overhead |
12+
| Maintain reversibility | Shadow phase keeps monorepo as source of truth until adoption proves value |
13+
| Enforce quality gates | Prevent silent export breaks and bundle bloat pre‑extraction |
14+
| Provide clean history | Optional subtree split for auditable evolution |
15+
16+
---
17+
18+
## 2. Readiness Prerequisites (Monorepo)
19+
20+
All should be green/stable before starting the shadow repo:
21+
22+
- `npm run spc:validate` PASS (build, SSR, export diff, size, CSS artifact)
23+
- Export surface snapshot established
24+
- Bundle gzip baseline recorded (`index.esm.js` & `spc.css`)
25+
- Alias convergence complete (only root `@/` in barrels)
26+
27+
---
28+
29+
## 3. Phase 1 – Shadow Repo Creation (Now)
30+
31+
1. Create new private repo: `nhs-fdp-spc` (enterprise template: CODEOWNERS, Dependabot, branch protection).
32+
2. Choose content import strategy:
33+
- Simple copy (fast): copy `packages/nhs-fdp-spc/` plus LICENSE & README.
34+
- History preserving: subtree split (see Appendix A) of `packages/nhs-fdp-spc` (+ optionally SPC source directories once internalised).
35+
3. Add minimal files (if copy strategy):
36+
- `package.json` (scoped name, repository, bugs, homepage, exports, types)
37+
- `README.md`, `CHANGELOG.md`, `LICENSE`, `CODE_OF_CONDUCT.md` (if needed)
38+
4. Set version to `0.0.0-alpha.0` (pre‑release tag only).
39+
5. Configure `.npmrc` (GitHub Packages) & add publish tokens as repo secrets.
40+
41+
---
42+
43+
## 4. Phase 2 – Shadow CI Workflows
44+
45+
Recommended single workflow (or split):
46+
47+
| Job | Scripts | Purpose |
48+
|-----|---------|---------|
49+
| install | `npm ci` | Deterministic dependencies |
50+
| build | `npm run build:spc` | JS + CSS integrity |
51+
| validate | `npm run spc:validate` | Gates: size, SSR, exports, CSS |
52+
| exports-check | `npm run spc:exports:check` | Prevent accidental removals |
53+
| adoption-report (optional early) | (n/a – runs only in monorepo) | Not needed once extracted |
54+
| test (optional) | `npm test` (if unit subset copied) | Lock behaviour early |
55+
| publish (manual dispatch) | `npm publish --tag alpha` | Dry-run releases |
56+
57+
Artifacts / outputs:
58+
59+
- Upload dist (optional) for inspection.
60+
- Generate summary with gzip sizes & export delta count.
61+
62+
---
63+
64+
## 5. Phase 3 – Ongoing Sync (Until Flip)
65+
66+
During shadow phase the monorepo stays authoritative. Keep the shadow repo updated by either:
67+
68+
1. Manual PRs: Periodically re-copy changes from monorepo SPC package.
69+
2. Automation: A monorepo workflow triggered on `packages/nhs-fdp-spc/**` changes pushing to shadow (PAT secret). Ensure generated commits are labelled (e.g. `chore(shadow-sync): …`).
70+
71+
Release strategy: publish only `alpha` / `beta` tags; do not mark `latest`.
72+
73+
---
74+
75+
## 6. Phase 4 – Readiness Gates
76+
77+
Flip to canonical only when ALL pass:
78+
79+
| Gate | Target | Source |
80+
|------|--------|--------|
81+
| Adoption | ≥70% of SPC import lines use `@nhs-fdp/spc` | `npm run spc:adoption` (monorepo) |
82+
| Export stability | 2 consecutive minor cycles with no breaking removals | export snapshot checks |
83+
| CI health | 100% green on build + validate + parity | shadow repo CI |
84+
| Parity completeness | Canonical numeric fixtures (XmR, T, G) unskipped | parity tests |
85+
| Size budget | gzipped ESM bundle < target (e.g. 120KB tightened) | validate output |
86+
| Documentation | Migration guide & external README finalised | docs |
87+
88+
---
89+
90+
## 7. Phase 5 – Canonical Flip
91+
92+
1. Final announcement & migration window (e.g. 4–6 weeks) posted in internal comms & CHANGELOG.
93+
2. Shadow repo publishes first stable version (e.g. `0.1.0`).
94+
3. Monorepo updates:
95+
- Replace legacy re-exports with a thin dependency on `@nhs-fdp/spc` OR mark as deprecated with console warning.
96+
- Update internal documentation to point to new repo.
97+
4. Monitor for regressions (error rate, bundle size changes in consumers).
98+
5. After window expires, remove deprecated legacy exports.
99+
100+
Rollback (if needed):
101+
102+
- Re-point consumers back to monorepo package version; publish patch release from monorepo including latest shadow code (subtree re-import if required).
103+
104+
---
105+
106+
## 8. Phase 6 – Post-Flip Hardening
107+
108+
- Introduce semantic release or conventional-changelog action for automated versioning.
109+
- Tighten size budgets; track delta per PR.
110+
- Add provenance: SBOM generation & license scan (if mandated by org policy).
111+
- Consider splitting engine & UI sub-entries if adoption for pure logic emerges.
112+
113+
---
114+
115+
## 9. Metrics & Reporting
116+
117+
| Metric | Source | Action Threshold |
118+
|--------|--------|------------------|
119+
| Adoption % | `spc:adoption` | <70% → extend migration support |
120+
| Bundle size delta | CI summary | >5% increase → require justification |
121+
| Export churn | `spc:exports:check` diff count | >0 unintended → block merge |
122+
| Parity failures | parity job | Any → block release |
123+
124+
---
125+
126+
## 10. Risks & Mitigations
127+
128+
| Risk | Mitigation |
129+
|------|-----------|
130+
| Divergent code between monorepo & shadow | Automate sync; diff on each PR |
131+
| Hidden deep imports bypassing public API | Export snapshot + codemod enforcement |
132+
| Size creep after extraction | CI size budget & trend report |
133+
| Consumer lag on migration | Early comms + codemods + adoption dashboard |
134+
135+
---
136+
137+
## Appendix A – Subtree Split (History Preservation)
138+
139+
```bash
140+
# From monorepo root (ensure clean working tree)
141+
git checkout master
142+
git pull
143+
144+
# 1. Create subtree branch for SPC package history only
145+
git subtree split --prefix=packages/nhs-fdp-spc -b spc-package-history
146+
147+
# 2. (Optional) Add additional SPC source paths once isolated
148+
# Repeat subtree split for each additional path if needed
149+
150+
# 3. Push to new (empty) shadow repo
151+
git remote add spc-origin [email protected]:<org>/nhs-fdp-spc.git
152+
git push spc-origin spc-package-history:main
153+
```
154+
155+
If you also want engine source history that still lives outside the package, migrate those files physically into the package in the monorepo first, then repeat the split to ensure continuity.
156+
157+
---
158+
159+
## Appendix B – Minimal Shadow CI Workflow (Conceptual)
160+
161+
```yaml
162+
name: spc-ci
163+
on:
164+
push:
165+
branches: [ main ]
166+
pull_request:
167+
branches: [ main ]
168+
169+
jobs:
170+
build-validate:
171+
runs-on: ubuntu-latest
172+
steps:
173+
- uses: actions/checkout@v4
174+
- uses: actions/setup-node@v4
175+
with:
176+
node-version: 22
177+
cache: npm
178+
- run: npm ci
179+
- run: npm run build:spc
180+
- run: npm run spc:validate
181+
- run: npm run spc:exports:check
182+
- name: Bundle summary
183+
run: |
184+
echo 'Bundle sizes:' >> $GITHUB_STEP_SUMMARY
185+
npx gzip-size-cli packages/nhs-fdp-spc/dist/index.esm.js >> $GITHUB_STEP_SUMMARY || true
186+
```
187+
188+
---
189+
190+
## Appendix C – Migration Communication Template
191+
192+
> We are promoting `@nhs-fdp/spc` to its own repository. Legacy imports via `@nhs-fdp/design-system` will remain for a deprecation window of 6 weeks. Please run `npm run spc:codemod:imports` to migrate. Track progress with `npm run spc:adoption`. Report issues in #spc-migration.
193+
194+
---
195+
196+
## Change Log (Playbook)
197+
198+
| Date | Change |
199+
|------|--------|
200+
| 2025-11-10 | Initial version added alongside adoption metrics script |

0 commit comments

Comments
 (0)