From 8ace948f1b08080c8d8dc7f421d1297bbc4e2d4a Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Sun, 31 May 2026 21:21:35 +0200 Subject: [PATCH] docs(reusable-workflows): fix CI gaps upstream, not per-project MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A /retro session on 2026-05-31 (session 743f82e8) surfaced a standing user preference stated during TYPO3 extension work: 'DRY — we use re-usable workflows so all our projects gain from improvements', with the instruction to check the shared typo3-ci reusable-workflow repo before patching a project. Adds pitfall #6 to reusable-workflow-pitfalls.md: when a CI/quality gap surfaces in a consumer, fix it in the shared reusable-workflow repo so every consumer inherits it, rather than patching the single project. Distinct from the existing pitfalls (#1-#5 cover how to author/reference; this covers where a fix belongs) and from reusable-workflow-security.md (SHA pinning). Signed-off-by: Sebastian Mendel --- .../references/reusable-workflow-pitfalls.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/skills/github-project/references/reusable-workflow-pitfalls.md b/skills/github-project/references/reusable-workflow-pitfalls.md index a6fae9e..224b574 100644 --- a/skills/github-project/references/reusable-workflow-pitfalls.md +++ b/skills/github-project/references/reusable-workflow-pitfalls.md @@ -85,3 +85,13 @@ Provide inline defaults only as a *fallback*, when the repo has no config of its - name: Lint uses: some/yamllint-action@ # picks up the repo's config, or the fallback ``` + +## 6. Fix the gap in the shared workflow, not per-project + +When CI or quality logic lives in a shared reusable workflow (e.g. `netresearch/typo3-ci-*`), a gap or bug that surfaces in one consumer is almost always a gap in the **shared** workflow. Fix it upstream so every consumer inherits the fix — do not patch the single project's `.github/workflows/`. + +Per-project patches defeat the point of the reusable workflow: they reintroduce the duplication the shared workflow exists to remove, drift out of sync as the shared workflow evolves, and force the same fix to be rediscovered in the next repo. + +Before adding a guard, check, or fix to a project's own workflow files, ask whether the shared reusable-workflow repo already owns that concern — or should. If it does, land the change there and let the consumer pick it up via its `@main` / `@vX.Y.Z` reference (per [`reusable-workflow-security.md`](./reusable-workflow-security.md), internal reusable workflows are referenced by tag/branch, not SHA). Keep logic in a consumer only when it is genuinely project-specific. + +This is distinct from pitfalls #1–#5 above (which cover *how* to author and reference reusable workflows) — this is about *where* a fix belongs.