Plan MIL-013: source code comments are in English
Adds MIL-013 (accepted, RC-083), objective O7 to the Business Case (RC-084), the schedule row, risk and dependency to the Project Plan, and the traceability rows. No code is added by this commit.
This commit is contained in:
@@ -0,0 +1,73 @@
|
||||
# Review Record: MIL-013 and PP-001 (MIL-013)
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | RC-083 |
|
||||
| CrossReference | [MIL-013], [PP-001], [BC-001], [QC-MIL-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat as stand-in for S01, after one correction found in the first read | pending |
|
||||
|
||||
---
|
||||
|
||||
## Artifact Under Review
|
||||
|
||||
- Instance reviewed: [MIL-013]; delta of [PP-001] for the added milestone
|
||||
- Checklist used: [QC-MIL-001] for the milestone; for the plan, the criteria of `PP.md` (no QC checklist exists for PP-001)
|
||||
- Scope: full review of MIL-013; delta re-review of PP-001, earlier record [RC-080]
|
||||
- Language and domain: n/a (technical type)
|
||||
- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, asked in chat on 2026-10-19 for the acceptance and stands in for S01; the AI prepared the evidence)
|
||||
|
||||
## Checklist Results
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | A concrete deliverable is defined for every gate | Pass | `## Deliverable` names release 2.3.0 with the reusable workflow, its scripts under `tools/`, guide, README section, wiki pages in three languages, changelog entry, offline tests, an ADR for the detection method and a review record, and the two pull requests in the other repositories. |
|
||||
| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Eleven criteria, each with a checkable Go and No-Go. The first is measurable (a corpus of named size, recall of at least 90 % for Danish and Malay, at most one false positive per 200 English comments); the others are runs, searches or a verified setting. Criterion 7 (the merge is blocked) depends on a setting that only the repository owner makes, and says so. |
|
||||
| 3 | Dependencies on other milestones are explicitly mapped | Pass | [MIL-010] (the comment scanner), [MIL-004] (the Release workflow), [MIL-011] (`MAJOR_TAG`), [ADR-0005]; the outside dependencies (a Gitea token from S03, branch protection by S01 or S03, the framework and checklist repositories) are named. The first read noted that the planned window of [MIL-004] (2026-11-16 to 2026-11-28) starts after this milestone does; [MIL-004] is already released (`v1`, `v2`), so the dependency is met and the plan says nothing wrong. |
|
||||
| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Objective O7 and success criterion 7 of [BC-001], added in the same change and reviewed in [RC-084]. The first read found the traceability row still saying O7 was "added at acceptance of this milestone", which is now false; it states the objective plainly. |
|
||||
| 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01; both are in [SA-001]. |
|
||||
| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-11-20, confirmed by S01 in chat on 2026-10-19; the Business Case sets no deadline. The window (2026-11-09 to 2026-11-20) follows [MIL-012] (2026-11-06) and overlaps [MIL-009], which is wiki callers and does not use the check's token or reviewer. |
|
||||
|
||||
## Plan delta (PP-001)
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | Every milestone has a `MIL-*` document and the plan's dates equal that document's target date | Pass | MIL-001 to MIL-013 exist; the MIL-013 decision date (2026-11-20) equals its Target Date. |
|
||||
| 2 | Every Business Case scope item is covered by a gateway | Pass | The new scope item "A shared workflow that checks that comments in source code are in English and tells the author" is covered by [MIL-013] in the scope table. |
|
||||
| 3 | The schedule respects the Business Case constraints | Pass | No deadline in the Business Case; the window is two weeks. |
|
||||
| 4 | Dependencies between milestones are stated | Pass | `MIL-004 + MIL-010 + MIL-011 -> MIL-013`. |
|
||||
| 5 | Every gateway has an owner who is a stakeholder ID | Pass | S05. |
|
||||
| 6 | Plan content is internally consistent | Pass | The Purpose says "thirteen"; the Gantt, the schedule, the scope table, the dependencies and the planning assumption agree. Unused commit link definitions left by the history roll were removed. |
|
||||
| 7 | Open Issues are current | Pass | A plan risk is added: the check calls a correct comment non-English or misses a Danish or Malay one, with the mitigation in tasks 1 and 2 and the exception marker. |
|
||||
|
||||
## Overall Verdict
|
||||
|
||||
Go - all criteria pass after one correction found in the first read (the stale "added at acceptance" wording). The author confirmed the acceptance in chat on 2026-10-19 as stand-in for S01; this is not an independent review.
|
||||
|
||||
## Action Items
|
||||
|
||||
| Action | Owner | Due |
|
||||
| --- | --- | --- |
|
||||
| Confirm this record by S01 when an independent reading is possible | S01 | 2026-11-02 |
|
||||
| Task 9: decide which repositories mark the check as required and set it; the workflow cannot, and the AI does not change branch protection | S01 | Before task 8 ends |
|
||||
| Ask the operator for a Gitea token that may comment on pull requests, stored as an organization secret, before task 8 | S03 | 2026-11-13 |
|
||||
|
||||
---
|
||||
|
||||
[MIL-013]: ../../milestones/mil-013-english-comments-check.md
|
||||
[PP-001]: ../../project-plan.md
|
||||
[BC-001]: ../../business-case.md
|
||||
[SA-001]: ../../stakeholder-analysis.md
|
||||
[MIL-004]: ../../milestones/mil-004-versioned-release.md
|
||||
[MIL-009]: ../../milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md
|
||||
[MIL-010]: ../../milestones/mil-010-code-metrics-badges.md
|
||||
[MIL-011]: ../../milestones/mil-011-code-metrics-default-tools-ref.md
|
||||
[MIL-012]: ../../milestones/mil-012-vpn-actions-for-deployment.md
|
||||
[ADR-0005]: ../../adr/adr-0005-quality-check-contract.md
|
||||
[RC-080]: ./rc-080-mil-012-plan.md
|
||||
[RC-084]: ./rc-084-bc-001-o7.md
|
||||
[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
|
||||
@@ -0,0 +1,53 @@
|
||||
# Review Record: BC-001 (objective O7, English comments check)
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | RC-084 |
|
||||
| CrossReference | [BC-001], [QC-BC-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat as stand-in for S01 | pending |
|
||||
|
||||
---
|
||||
|
||||
## Artifact Under Review
|
||||
|
||||
- Instance reviewed: [BC-001]
|
||||
- Checklist used: [QC-BC-001]
|
||||
- Scope: delta re-review of criteria 2, 3, 4 and 7 (the change adds objective O7, an In Scope bullet, an assumption, a constraint and success criterion 7); criteria 1, 5, 6 and 8 are re-read and unchanged. Earlier record: [RC-081]
|
||||
- Language and domain: n/a for this delta (the action item of [RC-067] about the Language and Domain rows is still open)
|
||||
- Language reviewer: none
|
||||
- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, asked in chat on 2026-10-19 for the acceptance and stands in for S01; the AI prepared the evidence)
|
||||
|
||||
## Checklist Results
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | ROI/Cost-Benefit analysis is quantitative, or where qualitative, is explicitly justified | Pass | Unchanged; the Cost-Benefit Assessment labels its qualitative form. |
|
||||
| 2 | Risks are identified with documented impact and mitigation | Pass | The delivery risk (the check wrongly flags a correct comment, or misses a Danish or Malay one) is a plan risk in PP-001 with a mitigation: a measured corpus before the build, an exception marker and an allowed-words file. |
|
||||
| 3 | Success criteria are measurable, stating explicit targets rather than vague aspirations | Pass | Criterion 7: "0 after MIL-013" non-English comments reaching the default branch of a repository that calls the check, measured by the check's run on the default branch and a throwaway pull request that cannot be merged. |
|
||||
| 4 | Scope explicitly separates In Scope vs Out of Scope | Pass | "A shared workflow that checks that comments in source code are in English and tells the author (MIL-013)" is a new In Scope bullet. Out of Scope is unchanged and does not contradict it: "application code of consuming repositories" stays out because the check only reads comments and reports them, and changes nothing in the consuming repository; "operating the Gitea instance or runners" stays out because branch protection is set by S01 or S03, as the new assumption says. |
|
||||
| 5 | Stakeholders are cross-referenced to Stakeholder Analysis IDs rather than re-described inline | Pass | Unchanged; the new assumption names S01 and S03. |
|
||||
| 6 | Methodology and quality-standard foundation are stated explicitly (e.g. ISO/IEC 25010, Larman) | Pass | Unchanged. |
|
||||
| 7 | Assumptions and constraints are explicit and clearly distinguished from one another | Pass | The assumption (S03 provides a token that may comment on pull requests; S01 or S03 mark the check required) and the constraint (no source text leaves the instance, the token never appears in a log) are in their own sections. |
|
||||
| 8 | Document supports executive decision-making with a clear, unambiguous recommendation | Pass | Unchanged: Proceed. |
|
||||
|
||||
## Overall Verdict
|
||||
|
||||
Go - all eight criteria pass for the revision that adds objective O7, its scope item, assumption, constraint and success criterion 7. The author confirmed the acceptance in chat on 2026-10-19 as stand-in for S01; there is no independent reader and the decision stays open to challenge.
|
||||
|
||||
## Action Items
|
||||
|
||||
| Action | Owner | Due |
|
||||
| --- | --- | --- |
|
||||
| The Metadata table of BC-001 has no `Language` and `Domain` rows (QC-LANG-001 criterion 1); this predates this change and is carried over from [RC-067]. Add the rows or record in an ADR why they are not needed | S01 | Before the next material change to BC-001 |
|
||||
|
||||
---
|
||||
|
||||
[BC-001]: ../../business-case.md
|
||||
[QC-BC-001]: ../../../framework/qc/artifacts/qc-business-case.md
|
||||
[RC-067]: ./rc-067-bc-001-o5.md
|
||||
[RC-081]: ./rc-081-bc-001-o6.md
|
||||
Reference in New Issue
Block a user