diff --git a/AGENTS.md b/AGENTS.md index 1d5749d..4ac124c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -119,6 +119,23 @@ A change that spans repositories: inside the accepted plan only if the plan names it; otherwise the run stops and reports. +## Workflow adoption rules + +When a workflow is added to this repository (`.gitea/workflows/`, +`.gitea/scoped_workflows/`) or a composite action to `actions/`, the same pull +request adds its rule for when a repository uses it in SQA and QC: + +1. A row in `guides/adoption-rules.md` with the columns *Use when*, *Do not use + when* and *What it gives SQA and QC*. The condition is checkable from the + repository itself (a file type, a test report, a wiki folder), never + "when useful". +2. The workflow's guide and its README section link to that row, and the + README workflow table and count stay in step. +3. A workflow that applies to every repository (scoped) or only to this one + says so in the row instead of leaving it empty. +4. The rule is changed in the same pull request as the workflow when the + workflow's behaviour changes; the CHANGELOG entry names it. + ## Workflow order Business Case, Stakeholder Analysis, Project Plan, milestones, tasks synced as diff --git a/CHANGELOG.md b/CHANGELOG.md index eb5abcb..d80e7bf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,10 @@ Each release lists its changes in these groups, in this order: ## [Unreleased] +### Added + +- The [adoption rules](guides/adoption-rules.md): for each workflow, when a repository uses it in SQA and QC. A new workflow adds its rule in the same pull request (`AGENTS.md`). + ## [2.2.0] - 2026-10-21 ### Added diff --git a/README.md b/README.md index a44bfb7..97ca937 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,8 @@ It contains eleven workflows: metadata sync to the GitHub mirror, wiki publishin ## 🔧 Workflows +When a repository should use each workflow in its SQA and QC is set out in the [adoption rules](guides/adoption-rules.md). + Eleven workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source. | Workflow | File | Kind | Starts on | Purpose | diff --git a/framework b/framework index 408e3a5..ca18cb4 160000 --- a/framework +++ b/framework @@ -1 +1 @@ -Subproject commit 408e3a5ace636e0ced31112dfc243d6578ffac43 +Subproject commit ca18cb421506a388f8be6010b3882a94d3503315 diff --git a/guides/adoption-rules.md b/guides/adoption-rules.md new file mode 100644 index 0000000..d538138 --- /dev/null +++ b/guides/adoption-rules.md @@ -0,0 +1,23 @@ +# When a repository uses a workflow + +Each workflow of this repository has one rule here that says when a repository +of the organisation, in its SQA and QC, should use it. The rule is the opt-in +test: a repository that meets the "Use when" condition calls the workflow, and a +review of that repository (SQA) checks that it does. A repository that does not +meet the condition does not call it. + +A new workflow is not finished until its row is in the table below +(`AGENTS.md`, rule "Workflow adoption rules"). + +| Workflow | Use when | Do not use when | What it gives SQA and QC | +| --- | --- | --- | --- | +| Sync GitHub mirror metadata | Scoped: nothing to do. Every repository of the organisation gets it, so a repository has a GitHub push mirror only if it needs one. | The repository has no GitHub mirror. | The mirror shows the same description and topics as the source of truth. | +| Quality checks | The repository tracks Python (`*.py`) or shell (`*.sh`) files. | It has neither. | Evidence for the code checklists that formatting, typing and shell lint are clean before a merge. Mark the check required in the branch protection. | +| Quality checks C++ | The repository tracks C or C++ files. | It has none. | The same evidence for C and C++, at exact tool versions. | +| Quality checks C# | The repository tracks C# files and can restore packages from the network. | It has none, or cannot reach the package source. | The same evidence for C#, on an exact .NET SDK. | +| Code metrics | The repository has a test suite that writes a Cobertura report and its README or wiki shows size and coverage. | It has no tests, or no report is produced. | Coverage and size as badges, so a reviewer sees them without running anything. | +| English comments | The repository's code comments must be English (the project's language rule) and it takes pull requests. | The project's language rule allows other languages in comments. | Enforces the language rule on every pull request, with the author named. Mark it required to block the merge. | +| Publish wiki pages | The repository has a wiki and its pages are written as Markdown under `docs/wiki/` (or `wiki_dir`). | It has no wiki, or the wiki is edited by hand. | The wiki equals the reviewed files; a page change goes through a pull request and its review. | +| Release | Opt-in is not by call: it is for repositories that publish versioned releases pinned by others, and it is run only in this repository. | Not applicable to other repositories. | A tagged, checked release other repositories can pin. | +| Publish accepted milestones | Internal to this repository (it reads this repository's milestones and reviews). A project that keeps `docs/milestones/` and `docs/sqa/reviews/` uses the framework's `templates/ci/` copy. | The repository has no `MIL-*` documents. | Only a milestone that is Accepted with a Go review becomes an issue (the plan-first gate). | +| Validate workflows | Internal: it gates this repository's own pull requests. | Not applicable to other repositories. | Proof that every workflow parses and passes the offline tests. |