From 30e37f45af25d3f530a56ab3f616ccc1b2edc041 Mon Sep 17 00:00:00 2001 From: danbaruka <46156791+danbaruka@users.noreply.github.com> Date: Tue, 4 Aug 2026 11:23:40 +0400 Subject: [PATCH] docs: add repository health review for CI, deps, and backlog Snapshot of deploy workflow overlap, npm/Dependabot risk on main, and open issue/PR triage priorities as of 2026-08-04. --- .../Maintainer/repo-health-review-2026-08.md | 198 ++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 DA Milestones/Maintainer/repo-health-review-2026-08.md diff --git a/DA Milestones/Maintainer/repo-health-review-2026-08.md b/DA Milestones/Maintainer/repo-health-review-2026-08.md new file mode 100644 index 0000000..8470a72 --- /dev/null +++ b/DA Milestones/Maintainer/repo-health-review-2026-08.md @@ -0,0 +1,198 @@ +# Repository Health Review — 2026-08-04 + +**Repo:** [IntersectMBO/developer-experience](https://github.com/IntersectMBO/developer-experience) +**Branch:** `chore/repo-health-review` +**Reviewer:** Dan Baruka +**Scope:** CI/CD, dependencies, backlog + +--- + +## Executive summary + +| Area | Status | Notes | +| --- | --- | --- | +| CI/CD | Needs improvement | Deploy works on `main`, but two overlapping Pages workflows and no PR build check | +| Dependencies | Critical | `npm audit` on `main`: **174** vulns (1 critical, 51 high); 58 open Dependabot alerts | +| Backlog | Needs triage | 12 open issues + 14 open PRs; several stale; branch count high (~34) | +| Branch protection | Unverified / likely weak | API returned 404 for protection rules (may mean none configured for this token/role) | + +**Immediate priorities** + +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) +2. Deduplicate GitHub Pages deploy workflows +3. Add a `pull_request` CI job that runs `npm ci` + `npm run build` in `website/` +4. Triage stale PRs and run branch cleanup ([#135](https://github.com/IntersectMBO/developer-experience/issues/135)) + +--- + +## 1. CI/CD + +### What exists + +| Workflow | Trigger | Role | +| --- | --- | --- | +| `.github/workflows/deploy.yml` | `push` to `main`, `workflow_dispatch` | Build (`npm ci` + `npm run build`) then deploy Pages | +| `.github/workflows/static.yml` | `push` to `main` when `website/**` changes, `workflow_dispatch` | Second full build + deploy to the same Pages environment | +| `.github/workflows/changelog.yml` | version tags | Soft-check that `CHANGELOG.md` mentions the tag | + +Recent deploy runs on `main` (e.g. after PR #251) completed **successfully**. Dependabot update jobs also succeed. + +### Findings + +1. **Duplicate Pages deploy pipelines** + 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. + **Recommendation:** Keep one workflow (prefer `deploy.yml` with `npm ci` + artifact upload). Delete or disable `static.yml`. + +2. **No pull-request CI** + Docs/site PRs are not built until merge to `main`. Broken links (`onBrokenLinks: throw`) and build failures only surface post-merge. + **Recommendation:** Add a lightweight `ci.yml` on `pull_request` paths `website/**` that runs: + + ```bash + cd website && npm ci && npm run build + ``` + +3. **Changelog workflow likely incomplete at repo root** + `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. + **Recommendation:** Point install/build at `website/` if needed, or replace with a docs-only check / release script that matches how versions are actually cut. + +4. **Action version drift** + 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. + +5. **Branch protection** + Could not read protection rules via API (404). Confirm in GitHub settings that `main` requires PR reviews and status checks once PR CI exists. + +### Suggested CI target state + +```text +pull_request (website/**) → npm ci + build +push main → single Pages deploy workflow +tags v* → changelog/release check (optional, fixed paths) +``` + +--- + +## 2. Dependencies + +### Audit snapshot (`website/` on `main`, 2026-08-04) + +```text +npm audit: 174 vulnerabilities + critical: 1 + high: 51 + moderate: 119 + low: 3 +``` + +### Open Dependabot alerts (org repo) + +| Severity | Count | +| --- | --- | +| critical | 2 | +| high | 28 | +| medium | 20 | +| low | 8 | +| **total** | **58** | + +**Packages involved (unique):** +`body-parser`, `brace-expansion`, `dompurify`, `fast-uri`, `http-proxy-middleware`, `js-yaml`, `postcss`, `shell-quote`, `svgo`, `undici`, `webpack-dev-server`, `websocket-driver` + +### Mitigations already in flight + +- 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. +- `website/package.json` already uses overrides, but several pins on `main` remain inside vulnerable ranges until #260 lands. +- Dependabot is configured weekly for npm (`/website`) and GitHub Actions, with grouping for Docusaurus/babel/webpack. + +### Quality notes + +- 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. +- `gray-matter` patch via `patch-package` is required for js-yaml 4 compatibility; keep until upstream/Docusaurus removes the need. +- Open Dependabot PRs (#255–#258, #253, #245, #235) should be rebased/merged after the security override PR to reduce conflict churn. + +### Recommendations + +1. Merge security fix PR (#260) or equivalent as soon as reviewed. +2. After merge, confirm Dependabot alerts close; close superseded Dependabot PRs. +3. Standardize on **npm** for `website/` (match CI) or migrate CI to Yarn — do not keep both as first-class without a written policy. +4. Add `npm run audit:ci` (`--audit-level=high`) as a non-blocking or blocking check in PR CI once baseline is clean. + +--- + +## 3. Backlog + +### Open issues (12) + +| # | Age (opened) | Labels | Title | Suggested action | +| --- | --- | --- | --- | --- | +| 259 | 2026-08-03 | Security, High | Fix security/quality deps | Merge paired PR #260 | +| 232 | 2026-05-20 | High, good first issue | Session widget wrong link | Good candidate for next fix sprint | +| 217 | 2026-04-16 | — | Duplicate home CTA buttons | Overlaps PR #218; triage together | +| 201 | 2026-03-25 | — | Core contributor pathway gaps | Content; larger than a drive-by | +| 192 | 2026-03-17 | enhancement | Website Audit | Umbrella; close or turn into checklist after #191 | +| 191 | 2026-03-17 | documentation | Redundant empty pages | PR #261 in review | +| 185 | 2026-03-16 | Medium, good first issue | Menu click area | Keep as GFI | +| 150 | 2026-02-09 | good first issue | IntersectMBO page updates | Confirm still relevant | +| 135 | 2026-01-06 | Medium | Branch cleanup | Still valid (~34 branches) | +| 115 | 2025-11-24 | documentation | Missing tutorials content | Partially mitigated; still only one tutorial | +| 100 | 2025-10-30 | enhancement | Recording descriptions | Ongoing as sessions publish | +| 55 | 2025-05-21 | — | Linux-ARM releases | Likely off-scope for this docs site; close or transfer | + +### Open pull requests (14) + +| Bucket | PRs | Notes | +| --- | --- | --- | +| Security / deps (human) | #260 | Highest priority | +| Docs cleanup | #261 | Closes #191 | +| Dependabot | #258, #257, #256, #255, #253, #245, #235 | Rebase after #260 | +| Docs / changelog | #242, #236, #196 | Review or refresh | +| Feature / layout | #226, #218 | May need design review; #218 tied to #217 | + +Several PRs are **>30–90 days** old. Without triage they will keep conflicting with `main`. + +### Branches + +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). + +**Recommendation:** After merging current critical PRs, delete merged branches and archive abandoned ones (Dependabot recreates as needed). + +--- + +## 4. Action checklist + +### This week + +- [ ] Review/merge [#260](https://github.com/IntersectMBO/developer-experience/pull/260) (security deps) +- [ ] Review/merge [#261](https://github.com/IntersectMBO/developer-experience/pull/261) (redundant pages) +- [ ] Remove or disable duplicate `static.yml` Pages workflow +- [ ] Add `pull_request` build workflow for `website/` + +### This month + +- [ ] Triage Dependabot PRs post-#260 +- [ ] Branch cleanup pass (#135) +- [ ] Decide npm vs Yarn for `website/` +- [ ] Confirm `main` branch protection + required checks +- [ ] Close or re-scope #55 if not applicable to this repo +- [ ] Fix remaining content gaps (#115, #201) or split into smaller issues + +### Hygiene metrics to track + +| Metric | Baseline (2026-08-04) | Target | +| --- | --- | --- | +| `npm audit` high+critical | 52 | 0 | +| Open Dependabot alerts | 58 | <5 | +| Duplicate deploy workflows | 2 | 1 | +| PR CI on website changes | No | Yes | +| Open PRs older than 60 days | Several | 0 without owner comment | +| Remote branches | ~34 | <15 active | + +--- + +## 5. Out of scope for this document + +- Implementing the CI/workflow code changes (follow-up PR recommended) +- Rewriting tutorial/pathway content +- Closing third-party Dependabot PRs without maintainer approval + +--- + +*Generated as a maintainer health snapshot for Intersect DevEx. Update after #260/#261 land.*