Skip to content

Commit 7812ace

Browse files
Ranchhand87Ranchhand87
authored
Merge pull request #262 from danbaruka/chore/repo-health-review
docs: repository health review (CI/CD, dependencies, backlog)
2 parents ede374c + 30e37f4 commit 7812ace

1 file changed

Lines changed: 198 additions & 0 deletions

File tree

‎DA Milestones/Maintainer/repo-health-review-2026-08.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# Repository Health Review — 2026-08-04
2+
3+
**Repo:** [IntersectMBO/developer-experience](https://github.com/IntersectMBO/developer-experience)
4+
**Branch:** `chore/repo-health-review`
5+
**Reviewer:** Dan Baruka
6+
**Scope:** CI/CD, dependencies, backlog
7+
8+
---
9+
10+
## Executive summary
11+
12+
| Area | Status | Notes |
13+
| --- | --- | --- |
14+
| CI/CD | Needs improvement | Deploy works on `main`, but two overlapping Pages workflows and no PR build check |
15+
| Dependencies | Critical | `npm audit` on `main`: **174** vulns (1 critical, 51 high); 58 open Dependabot alerts |
16+
| Backlog | Needs triage | 12 open issues + 14 open PRs; several stale; branch count high (~34) |
17+
| Branch protection | Unverified / likely weak | API returned 404 for protection rules (may mean none configured for this token/role) |
18+
19+
**Immediate priorities**
20+
21+
1. Merge (or land equivalent of) security dependency fix — see [#259](https://github.com/IntersectMBO/developer-experience/issues/259) / [#260](https://github.com/IntersectMBO/developer-experience/pull/260)
22+
2. Deduplicate GitHub Pages deploy workflows
23+
3. Add a `pull_request` CI job that runs `npm ci` + `npm run build` in `website/`
24+
4. Triage stale PRs and run branch cleanup ([#135](https://github.com/IntersectMBO/developer-experience/issues/135))
25+
26+
---
27+
28+
## 1. CI/CD
29+
30+
### What exists
31+
32+
| Workflow | Trigger | Role |
33+
| --- | --- | --- |
34+
| `.github/workflows/deploy.yml` | `push` to `main`, `workflow_dispatch` | Build (`npm ci` + `npm run build`) then deploy Pages |
35+
| `.github/workflows/static.yml` | `push` to `main` when `website/**` changes, `workflow_dispatch` | Second full build + deploy to the same Pages environment |
36+
| `.github/workflows/changelog.yml` | version tags | Soft-check that `CHANGELOG.md` mentions the tag |
37+
38+
Recent deploy runs on `main` (e.g. after PR #251) completed **successfully**. Dependabot update jobs also succeed.
39+
40+
### Findings
41+
42+
1. **Duplicate Pages deploy pipelines**
43+
Both `deploy.yml` and `static.yml` build and deploy to `github-pages` on pushes to `main`. That doubles CI minutes, can race on the same environment, and makes failures harder to reason about.
44+
**Recommendation:** Keep one workflow (prefer `deploy.yml` with `npm ci` + artifact upload). Delete or disable `static.yml`.
45+
46+
2. **No pull-request CI**
47+
Docs/site PRs are not built until merge to `main`. Broken links (`onBrokenLinks: throw`) and build failures only surface post-merge.
48+
**Recommendation:** Add a lightweight `ci.yml` on `pull_request` paths `website/**` that runs:
49+
50+
```bash
51+
cd website && npm ci && npm run build
52+
```
53+
54+
3. **Changelog workflow likely incomplete at repo root**
55+
`changelog.yml` runs `npm ci` at repository root, but there is no root `package.json`. The job mostly echoes a warning and does not regenerate the changelog.
56+
**Recommendation:** Point install/build at `website/` if needed, or replace with a docs-only check / release script that matches how versions are actually cut.
57+
58+
4. **Action version drift**
59+
Open Dependabot PRs bump `actions/checkout` and `actions/setup-node` to v7 while workflows still pin v6. Fine to batch with a single CI PR after deduplicating workflows.
60+
61+
5. **Branch protection**
62+
Could not read protection rules via API (404). Confirm in GitHub settings that `main` requires PR reviews and status checks once PR CI exists.
63+
64+
### Suggested CI target state
65+
66+
```text
67+
pull_request (website/**) → npm ci + build
68+
push main → single Pages deploy workflow
69+
tags v* → changelog/release check (optional, fixed paths)
70+
```
71+
72+
---
73+
74+
## 2. Dependencies
75+
76+
### Audit snapshot (`website/` on `main`, 2026-08-04)
77+
78+
```text
79+
npm audit: 174 vulnerabilities
80+
critical: 1
81+
high: 51
82+
moderate: 119
83+
low: 3
84+
```
85+
86+
### Open Dependabot alerts (org repo)
87+
88+
| Severity | Count |
89+
| --- | --- |
90+
| critical | 2 |
91+
| high | 28 |
92+
| medium | 20 |
93+
| low | 8 |
94+
| **total** | **58** |
95+
96+
**Packages involved (unique):**
97+
`body-parser`, `brace-expansion`, `dompurify`, `fast-uri`, `http-proxy-middleware`, `js-yaml`, `postcss`, `shell-quote`, `svgo`, `undici`, `webpack-dev-server`, `websocket-driver`
98+
99+
### Mitigations already in flight
100+
101+
- Issue [#259](https://github.com/IntersectMBO/developer-experience/issues/259) and PR [#260](https://github.com/IntersectMBO/developer-experience/pull/260) refresh `overrides` / `resolutions` and report **0** audit findings when applied.
102+
- `website/package.json` already uses overrides, but several pins on `main` remain inside vulnerable ranges until #260 lands.
103+
- Dependabot is configured weekly for npm (`/website`) and GitHub Actions, with grouping for Docusaurus/babel/webpack.
104+
105+
### Quality notes
106+
107+
- Both `package-lock.json` and `yarn.lock` exist under `website/` while `packageManager` declares Yarn and CI uses **npm**. Prefer one package manager in CI and docs to avoid drift.
108+
- `gray-matter` patch via `patch-package` is required for js-yaml 4 compatibility; keep until upstream/Docusaurus removes the need.
109+
- Open Dependabot PRs (#255–#258, #253, #245, #235) should be rebased/merged after the security override PR to reduce conflict churn.
110+
111+
### Recommendations
112+
113+
1. Merge security fix PR (#260) or equivalent as soon as reviewed.
114+
2. After merge, confirm Dependabot alerts close; close superseded Dependabot PRs.
115+
3. Standardize on **npm** for `website/` (match CI) or migrate CI to Yarn — do not keep both as first-class without a written policy.
116+
4. Add `npm run audit:ci` (`--audit-level=high`) as a non-blocking or blocking check in PR CI once baseline is clean.
117+
118+
---
119+
120+
## 3. Backlog
121+
122+
### Open issues (12)
123+
124+
| # | Age (opened) | Labels | Title | Suggested action |
125+
| --- | --- | --- | --- | --- |
126+
| 259 | 2026-08-03 | Security, High | Fix security/quality deps | Merge paired PR #260 |
127+
| 232 | 2026-05-20 | High, good first issue | Session widget wrong link | Good candidate for next fix sprint |
128+
| 217 | 2026-04-16 | — | Duplicate home CTA buttons | Overlaps PR #218; triage together |
129+
| 201 | 2026-03-25 | — | Core contributor pathway gaps | Content; larger than a drive-by |
130+
| 192 | 2026-03-17 | enhancement | Website Audit | Umbrella; close or turn into checklist after #191 |
131+
| 191 | 2026-03-17 | documentation | Redundant empty pages | PR #261 in review |
132+
| 185 | 2026-03-16 | Medium, good first issue | Menu click area | Keep as GFI |
133+
| 150 | 2026-02-09 | good first issue | IntersectMBO page updates | Confirm still relevant |
134+
| 135 | 2026-01-06 | Medium | Branch cleanup | Still valid (~34 branches) |
135+
| 115 | 2025-11-24 | documentation | Missing tutorials content | Partially mitigated; still only one tutorial |
136+
| 100 | 2025-10-30 | enhancement | Recording descriptions | Ongoing as sessions publish |
137+
| 55 | 2025-05-21 | — | Linux-ARM releases | Likely off-scope for this docs site; close or transfer |
138+
139+
### Open pull requests (14)
140+
141+
| Bucket | PRs | Notes |
142+
| --- | --- | --- |
143+
| Security / deps (human) | #260 | Highest priority |
144+
| Docs cleanup | #261 | Closes #191 |
145+
| Dependabot | #258, #257, #256, #255, #253, #245, #235 | Rebase after #260 |
146+
| Docs / changelog | #242, #236, #196 | Review or refresh |
147+
| Feature / layout | #226, #218 | May need design review; #218 tied to #217 |
148+
149+
Several PRs are **>30–90 days** old. Without triage they will keep conflicting with `main`.
150+
151+
### Branches
152+
153+
About **34** remote branches including many Dependabot and one-off session branches. Aligns with open issue [#135](https://github.com/IntersectMBO/developer-experience/issues/135).
154+
155+
**Recommendation:** After merging current critical PRs, delete merged branches and archive abandoned ones (Dependabot recreates as needed).
156+
157+
---
158+
159+
## 4. Action checklist
160+
161+
### This week
162+
163+
- [ ] Review/merge [#260](https://github.com/IntersectMBO/developer-experience/pull/260) (security deps)
164+
- [ ] Review/merge [#261](https://github.com/IntersectMBO/developer-experience/pull/261) (redundant pages)
165+
- [ ] Remove or disable duplicate `static.yml` Pages workflow
166+
- [ ] Add `pull_request` build workflow for `website/`
167+
168+
### This month
169+
170+
- [ ] Triage Dependabot PRs post-#260
171+
- [ ] Branch cleanup pass (#135)
172+
- [ ] Decide npm vs Yarn for `website/`
173+
- [ ] Confirm `main` branch protection + required checks
174+
- [ ] Close or re-scope #55 if not applicable to this repo
175+
- [ ] Fix remaining content gaps (#115, #201) or split into smaller issues
176+
177+
### Hygiene metrics to track
178+
179+
| Metric | Baseline (2026-08-04) | Target |
180+
| --- | --- | --- |
181+
| `npm audit` high+critical | 52 | 0 |
182+
| Open Dependabot alerts | 58 | <5 |
183+
| Duplicate deploy workflows | 2 | 1 |
184+
| PR CI on website changes | No | Yes |
185+
| Open PRs older than 60 days | Several | 0 without owner comment |
186+
| Remote branches | ~34 | <15 active |
187+
188+
---
189+
190+
## 5. Out of scope for this document
191+
192+
- Implementing the CI/workflow code changes (follow-up PR recommended)
193+
- Rewriting tutorial/pathway content
194+
- Closing third-party Dependabot PRs without maintainer approval
195+
196+
---
197+
198+
*Generated as a maintainer health snapshot for Intersect DevEx. Update after #260/#261 land.*

0 commit comments

Comments
 (0)