diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index ca105a93..41a56871 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -112,6 +112,10 @@ jobs: needs: changes if: needs.changes.outputs.python == 'true' runs-on: ubuntu-24.04 + permissions: + contents: read + # The coverage numbers are written into the pull request's description. + pull-requests: write defaults: run: working-directory: devcapsule-src @@ -169,6 +173,18 @@ jobs: --format markdown:diff-cover.md,json:diff-cover.json python scripts/diff_coverage_annotations.py + # Both figures go into the PR description between marker comments, so + # a merge that takes the description as its message carries them too. + - name: Publish coverage numbers to the pull request + if: github.event_name == 'pull_request' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ github.event.pull_request.number }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: | + python -m coverage json -o coverage.json + python scripts/publish_coverage_numbers_to_pr.py + - name: Publish coverage summary if: ${{ always() && hashFiles('devcapsule-src/.coverage') != '' }} run: | @@ -185,6 +201,7 @@ jobs: name: python-coverage path: | devcapsule-src/coverage.xml + devcapsule-src/coverage.json devcapsule-src/htmlcov/ devcapsule-src/diff-cover.md devcapsule-src/diff-cover.json diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index 5990e590..1b843315 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -11,7 +11,7 @@ coordination branch. Detailed state belongs in each linked status file. |---|---|---|---|---|---| | `workflow-improvements` | 2026-08-09 | Improve the multiple-stream workflow from concrete dogfood findings during the recursive E2E cycle | active 2026-10-30; Pair Review Loop naming implemented and packaging verified for 0.3.0; mainline and release integration pending | `ws-workflow-improvements/v1` | [workstream status](engineering-docs/wip/2026-08-09-workflow-improvements/CURRENT-STATUS.md) | | `project-management` | 2026-08-09 | Maintain project-wide priorities, sequencing, dependencies, and lifecycle coordination | paused 2026-10-11 at owner direction; consent and forced configuration before RC work; remaining diagnostics/image scope and release cut decisions retained | `ws-project-management/coordination` | [workstream status](engineering-docs/wip/2026-08-09-project-management/CURRENT-STATUS.md) | -| `maintenance` | 2026-09-18 | Own the defects no open workstream covers, on `main` and on maintained release lines, and drive maintenance releases | active 2026-11-03; unit-test conventions slice, PR #335, awaits the owner's merge; 0.3.1 queue preserved | `ws-maintenance/test-conventions`; `ws-maintenance/0.3.1-preparation` carried into it; `release-0.3.0` closed and retained | [workstream status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) | +| `maintenance` | 2026-09-18 | Own the defects no open workstream covers, on `main` and on maintained release lines, and drive maintenance releases | active 2026-11-04; #335 merged; coverage-numbers slice, PR #336, awaits the owner's merge; 0.3.1 queue preserved | `ws-maintenance/coverage-in-pr`; `ws-maintenance/test-conventions` merged through #335 and closed; `release-0.3.0` closed and retained | [workstream status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) | | `component-upgrades` | 2026-09-21 | Deliver component distribution channels, developer-owned version sets and proven upgrade rollback; Codex first | paused 2026-10-02; consent design ruled (D-0011 to D-0013), 0.2.16 consent slice next; R-UPGRADE-002 follow-up retained | `ws-component-upgrades/v1` | [workstream status](engineering-docs/wip/2026-09-21-component-upgrades/CURRENT-STATUS.md) | | `sample-projects` | 2026-08-14 | Provide realistic sample projects as submodules that demonstrate ordinary adopter development inside DevCapsule | integrating 2026-10-22; AI Learning published; PR #252 reviewed and ready for human merge | `ws-sample-projects/ai-learning` | [workstream status](engineering-docs/wip/2026-08-14-sample-projects/CURRENT-STATUS.md) | | `contained-display` | 2026-08-19 | Own the capsule supervisor core (container entry process, supervised children, explicit session end, headless mode) and the capsule's own display environment, closing the host-session credential exposure — supervisor first, display as its first consumer | active; **the contained display shipped in v0.2.12 on 2026-09-14** (recipe-9 base, contained desktop by default, X11 passthrough behind `host-x11`); the X11 credential bug is resolved; remaining threads are records and follow-ups (reconnect, WSL2 opener, sample locks) | `ws-contained-display/display-transport` | [workstream status](engineering-docs/wip/2026-08-19-contained-display/CURRENT-STATUS.md) | diff --git a/WORKFLOW-LOCAL.md b/WORKFLOW-LOCAL.md index 2ca37231..a0aac5e4 100644 --- a/WORKFLOW-LOCAL.md +++ b/WORKFLOW-LOCAL.md @@ -452,7 +452,10 @@ by merging `main` in. The hosting platform allows merge commits only. It deletes the head branch on merge. It refuses force pushes to `main` and deletion of `main`. The merge commit is the record of the branch: its second parent is the merged head and its message names the source branch. Delete a -merged branch. +merged branch. Owner setting, 2026-11-04: the merge commit's title is the +pull request's title and its message is the pull request's description, so +the description an agent writes, and the coverage block CI appends to it, +are the merge commit's detail as they stand at merge time. The earlier ruling that `ws-workflow-improvements/v1` rebases onto `main` is retired. That branch merges like the others. The engineering source is [merge strategy and commit identity](engineering-docs/implementation-notes/workflow/2026-08-17-merge-strategy-and-commit-identity.md). diff --git a/devcapsule-src/noxfile.py b/devcapsule-src/noxfile.py index eca38273..743e2d4d 100644 --- a/devcapsule-src/noxfile.py +++ b/devcapsule-src/noxfile.py @@ -176,6 +176,7 @@ def run_typecheck(session: nox.Session) -> None: str(VERSION_SCRIPT), str(PROJECT_ROOT / "scripts" / "release-manifest.py"), str(PROJECT_ROOT / "scripts" / "validate_unittests_follow_conventions.py"), + str(PROJECT_ROOT / "scripts" / "publish_coverage_numbers_to_pr.py"), str(PROJECT_ROOT / "scripts" / "release-protocol.py"), str(PROJECT_ROOT / "scripts" / "prepare-promotion.py"), ) diff --git a/devcapsule-src/pyproject.toml b/devcapsule-src/pyproject.toml index fd007a5c..e468bdeb 100644 --- a/devcapsule-src/pyproject.toml +++ b/devcapsule-src/pyproject.toml @@ -107,7 +107,7 @@ skip_covered = true [tool.mypy] python_version = "3.12" -files = ["devcapsule", "tests", "noxfile.py", "scripts/bump-version.py", "scripts/release-manifest.py", "scripts/ci_gate.py", "scripts/diff_coverage_annotations.py", "scripts/validate_unittests_follow_conventions.py"] +files = ["devcapsule", "tests", "noxfile.py", "scripts/bump-version.py", "scripts/release-manifest.py", "scripts/ci_gate.py", "scripts/diff_coverage_annotations.py", "scripts/validate_unittests_follow_conventions.py", "scripts/publish_coverage_numbers_to_pr.py"] # Sample projects are independent submodules with their own dependencies. They # are checked by their own tooling, not by DevCapsule's gate. exclude = "(^|/)tests/resources/sample_projects/" diff --git a/devcapsule-src/scripts/publish_coverage_numbers_to_pr.py b/devcapsule-src/scripts/publish_coverage_numbers_to_pr.py new file mode 100644 index 00000000..6f7f07bf --- /dev/null +++ b/devcapsule-src/scripts/publish_coverage_numbers_to_pr.py @@ -0,0 +1,164 @@ +"""Publish a pull request's coverage numbers into its description. + +Run from ``devcapsule-src`` after the tests and diff-cover steps, on a +``pull_request`` event only:: + + python -m coverage json -o coverage.json + python scripts/publish_coverage_numbers_to_pr.py + +The step reads ``coverage.json``, coverage.py's report of the whole +``devcapsule`` package, and ``diff-cover.json``, the report over the lines +the pull request changed. It renders one Markdown block between two marker +comments and replaces that block in the pull request's description, or +appends it when the description has none. The text outside the block is the +author's and is never touched. With the repository set to take the pull +request's description as the merge commit message, the numbers reach +``main``'s history unchanged. + +Environment: ``GITHUB_REPOSITORY``, ``PR_NUMBER``, ``GITHUB_TOKEN`` with +``pull-requests: write``, and ``RUN_URL`` for the link. No percentage fails +this step. A missing or malformed report, or a refused API call, does. +""" +from __future__ import annotations + +import argparse +import json +import os +import re +import sys +import urllib.request +from collections.abc import Mapping +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +__all__ = ["Numbers", "read_numbers", "render", "upsert", "main"] + +BEGIN = "" +END = "" +"""The markers that bound the block; each stands alone on its line, so a marker quoted in prose is not a block.""" + +_BLOCK = re.compile(rf"^{re.escape(BEGIN)}\n.*?^{re.escape(END)}$", re.MULTILINE | re.DOTALL) + +_API_VERSION = "2022-11-28" + + +@dataclass(frozen=True) +class Numbers: + """The two figures and what they are made of.""" + + overall_percent: float + """Statements of the ``devcapsule`` package covered, branch-aware as coverage.py reports it.""" + covered_statements: int + statements: int + diff_percent: int + """Changed measured lines covered, as diff-cover reports it.""" + diff_lines: int + """Changed lines the coverage report measures; test files and unmeasured lines are not among them.""" + diff_uncovered: int + + +def read_numbers(coverage: Mapping[str, Any], diff: Mapping[str, Any]) -> Numbers: + """The figures from coverage.py's JSON ``totals`` and diff-cover's JSON totals. + + Raises ``ValueError`` naming the first key a report lacks or mistypes. + """ + totals = coverage.get("totals") + if not isinstance(totals, Mapping): + raise ValueError("coverage.json: no 'totals' table") + try: + return Numbers( + overall_percent=float(totals["percent_covered"]), + covered_statements=int(totals["covered_lines"]), + statements=int(totals["num_statements"]), + diff_percent=int(diff["total_percent_covered"]), + diff_lines=int(diff["total_num_lines"]), + diff_uncovered=int(diff["total_num_violations"]), + ) + except KeyError as missing: + raise ValueError(f"report lacks {missing.args[0]!r}") from None + except (TypeError, ValueError) as wrong: + raise ValueError(f"report value is not a number: {wrong}") from None + + +def render(numbers: Numbers, run_url: str) -> str: + """The Markdown block, markers included, for one run.""" + return "\n".join([ + BEGIN, + f"### Test coverage, from [CI run]({run_url})", + "", + "| | |", + "|---|---|", + "| Changed lines covered | " + _changed_lines(numbers) + " |", + f"| Overall `devcapsule` | **{numbers.overall_percent:.1f}%** " + f"({numbers.covered_statements:,} of {numbers.statements:,} statements) |", + END, + ]) + + +def _changed_lines(numbers: Numbers) -> str: + """The changed-lines cell; a change outside the measured package says so instead of claiming 100% of nothing.""" + if numbers.diff_lines == 0: + return "none measured: the change touches no line of `devcapsule`" + return (f"**{numbers.diff_percent}%** ({numbers.diff_lines - numbers.diff_uncovered} of {numbers.diff_lines} " + f"measured changed lines; {numbers.diff_uncovered} uncovered)") + + +def upsert(body: str | None, block: str) -> str: + """The description with its block replaced, or the block appended after a blank line. + + Only a block whose markers each stand alone on a line is replaced; the + markers quoted inside the author's prose are prose. + """ + text = body or "" + found = _BLOCK.search(text) + if found: + return text[:found.start()] + block + text[found.end():] + return block if not text.strip() else text.rstrip("\n") + "\n\n" + block + + +def _request(method: str, url: str, token: str, payload: Mapping[str, Any] | None = None) -> dict[str, Any]: + data = None if payload is None else json.dumps(payload).encode() + request = urllib.request.Request(url, data=data, method=method, headers={ + "Authorization": f"Bearer {token}", + "Accept": "application/vnd.github+json", + "X-GitHub-Api-Version": _API_VERSION, + "Content-Type": "application/json", + }) + with urllib.request.urlopen(request) as response: # noqa: S310 - the URL is api.github.com, built here + return json.load(response) + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__.split("\n\n", 1)[0]) + parser.add_argument("--coverage", type=Path, default=Path("coverage.json")) + parser.add_argument("--diff", type=Path, default=Path("diff-cover.json")) + arguments = parser.parse_args(argv) + try: + numbers = read_numbers( + json.loads(arguments.coverage.read_text(encoding="utf-8")), + json.loads(arguments.diff.read_text(encoding="utf-8")), + ) + repository, number, token = (os.environ[name] for name in ("GITHUB_REPOSITORY", "PR_NUMBER", "GITHUB_TOKEN")) + run_url = os.environ.get("RUN_URL", "") + except (OSError, ValueError, KeyError) as problem: + print(f"coverage numbers: {problem}", file=sys.stderr) + return 1 + block = render(numbers, run_url) + url = f"https://api.github.com/repos/{repository}/pulls/{number}" + current = _request("GET", url, token).get("body") + updated = upsert(current, block) + if updated == current: + print("coverage numbers: the description already carries this run's numbers") + return 0 + try: + _request("PATCH", url, token, {"body": updated}) + except OSError as refused: + print(f"coverage numbers: the API refused the update: {refused}", file=sys.stderr) + return 1 + print(f"coverage numbers: changed lines {numbers.diff_percent}%, overall {numbers.overall_percent:.1f}%, published to #{number}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py b/devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py new file mode 100644 index 00000000..2a1961c2 --- /dev/null +++ b/devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py @@ -0,0 +1,155 @@ +"""Unit tests of ``scripts/publish_coverage_numbers_to_pr.py``: the figures, the block, the upsert, the step.""" +from __future__ import annotations + +import importlib.util +import json +import sys +from pathlib import Path +from typing import Any + +import pytest + +_SCRIPT = Path(__file__).resolve().parents[3] / "scripts" / "publish_coverage_numbers_to_pr.py" + + +def _load(path: Path) -> Any: + """The script as a module; registered in ``sys.modules`` so its dataclasses resolve their annotations.""" + spec = importlib.util.spec_from_file_location(path.stem, path) + assert spec and spec.loader + module = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = module + spec.loader.exec_module(module) + return module + + +publish = _load(_SCRIPT) + +COVERAGE = {"totals": {"percent_covered": 82.456, "covered_lines": 16012, "num_statements": 19488}} +DIFF = {"total_percent_covered": 87, "total_num_lines": 150, "total_num_violations": 20} + + +def test_the_figures_are_read_from_both_reports() -> None: + """Precondition: coverage.py totals and diff-cover totals as their JSON gives them. + Action: read. Postcondition: the six figures, typed, with nothing derived yet.""" + numbers = publish.read_numbers(COVERAGE, DIFF) + assert numbers == publish.Numbers(82.456, 16012, 19488, 87, 150, 20) + + +@pytest.mark.parametrize("coverage,diff,missing", [ + ({}, DIFF, "'totals'"), + ({"totals": {"percent_covered": 1.0}}, DIFF, "'covered_lines'"), + (COVERAGE, {"total_percent_covered": 1}, "'total_num_lines'"), +]) +def test_a_report_lacking_a_figure_is_refused_by_name(coverage: dict, diff: dict, missing: str) -> None: + """Precondition: one report lacks a key. Action: read. Postcondition: ValueError names that key.""" + with pytest.raises(ValueError, match=missing): + publish.read_numbers(coverage, diff) + + +def test_the_block_carries_both_percentages_between_the_markers() -> None: + """Precondition: the figures and a run URL. Action: render. Postcondition: the block + starts and ends with the markers, links the run, and states 87% of changed lines + with 130 of 150 covered, and 82.5% overall with the statement counts.""" + block = publish.render(publish.Numbers(82.456, 16012, 19488, 87, 150, 20), "https://ci/run/1") + lines = block.splitlines() + assert lines[0] == publish.BEGIN and lines[-1] == publish.END + assert "[CI run](https://ci/run/1)" in block + assert "**87%** (130 of 150 measured changed lines; 20 uncovered)" in block + assert "**82.5%** (16,012 of 19,488 statements)" in block + + +def test_upsert_appends_the_block_after_the_authors_text() -> None: + """Precondition: a description without markers. Action: upsert. + Postcondition: the author's text is intact, one blank line, then the block.""" + block = f"{publish.BEGIN}\nnumbers\n{publish.END}" + assert publish.upsert("## Why\n\nBecause.\n", block) == f"## Why\n\nBecause.\n\n{block}" + + +def test_upsert_replaces_only_the_block_between_the_markers() -> None: + """Precondition: a description with an older block between text above and below. + Action: upsert the new block. Postcondition: the text above and below is byte for + byte what it was and the old block is gone.""" + old = f"{publish.BEGIN}\nold\n{publish.END}" + new = f"{publish.BEGIN}\nnew\n{publish.END}" + assert publish.upsert(f"above\n\n{old}\n\nbelow\n", new) == f"above\n\n{new}\n\nbelow\n" + + +def test_markers_quoted_in_the_authors_prose_are_not_the_block() -> None: + """Precondition: a description that mentions both markers inside a sentence and has no block. + Action: upsert. Postcondition: the sentence is intact and the block is appended after it.""" + prose = f"It renders a block between `{publish.BEGIN}` and `{publish.END}` with the figures.\n" + block = f"{publish.BEGIN}\nnumbers\n{publish.END}" + assert publish.upsert(prose, block) == f"{prose}\n{block}" + + +def test_a_change_outside_the_measured_package_says_so_instead_of_a_percentage() -> None: + """Precondition: diff-cover measured no changed line. Action: render. + Postcondition: the changed-lines cell says none measured and names the package; no percent sign in it.""" + block = publish.render(publish.Numbers(82.456, 16012, 19488, 100, 0, 0), "https://ci/run/1") + cell = next(line for line in block.splitlines() if line.startswith("| Changed lines covered")) + assert "none measured: the change touches no line of `devcapsule`" in cell and "%" not in cell + + +def test_upsert_on_an_empty_description_is_the_block_alone() -> None: + """Precondition: the API returned no body. Action: upsert. Postcondition: the block alone.""" + block = f"{publish.BEGIN}\nnumbers\n{publish.END}" + assert publish.upsert(None, block) == block + + +def _reports(tmp_path: Path) -> list[str]: + (tmp_path / "coverage.json").write_text(json.dumps(COVERAGE)) + (tmp_path / "diff-cover.json").write_text(json.dumps(DIFF)) + return ["--coverage", str(tmp_path / "coverage.json"), "--diff", str(tmp_path / "diff-cover.json")] + + +def _environment(monkeypatch: pytest.MonkeyPatch) -> None: + for name, value in (("GITHUB_REPOSITORY", "o/r"), ("PR_NUMBER", "7"), ("GITHUB_TOKEN", "t"), ("RUN_URL", "https://ci/run/1")): + monkeypatch.setenv(name, value) + + +def test_main_reads_the_description_and_patches_it_with_the_block(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Precondition: both reports on disk, the environment set, a description without the block. + Action: run ``main`` with the API replaced by a recorder. Postcondition: one GET then one + PATCH of ``/repos/o/r/pulls/7`` whose body is the description plus the block; exit 0.""" + calls: list[tuple[str, str, dict | None]] = [] + + def api(method: str, url: str, token: str, payload: dict | None = None) -> dict: + calls.append((method, url, payload)) + return {"body": "The PR.\n"} if method == "GET" else {} + + monkeypatch.setattr(publish, "_request", api) + _environment(monkeypatch) + assert publish.main(_reports(tmp_path)) == 0 + assert [(m, u) for m, u, _ in calls] == [("GET", "https://api.github.com/repos/o/r/pulls/7"), + ("PATCH", "https://api.github.com/repos/o/r/pulls/7")] + body = calls[1][2]["body"] # type: ignore[index] + assert body.startswith("The PR.\n\n" + publish.BEGIN) and body.endswith(publish.END) + + +def test_main_does_not_patch_a_description_that_already_carries_this_block(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Precondition: the description already holds exactly this run's block. Action: run ``main``. + Postcondition: only the GET is made and the exit is 0.""" + block = publish.render(publish.read_numbers(COVERAGE, DIFF), "https://ci/run/1") + calls: list[str] = [] + + def api(method: str, url: str, token: str, payload: dict | None = None) -> dict: + calls.append(method) + return {"body": block} + + monkeypatch.setattr(publish, "_request", api) + _environment(monkeypatch) + assert publish.main(_reports(tmp_path)) == 0 + assert calls == ["GET"] + + +def test_main_fails_without_a_report_or_the_environment(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None: + """Precondition: the reports exist but the token is absent; then the reports are absent. + Action: run ``main`` twice. Postcondition: exit 1 each time with the cause on stderr, no API call.""" + monkeypatch.setattr(publish, "_request", lambda *a, **k: pytest.fail("no API call expected")) + _environment(monkeypatch) + monkeypatch.delenv("GITHUB_TOKEN") + assert publish.main(_reports(tmp_path)) == 1 + assert "GITHUB_TOKEN" in capsys.readouterr().err + monkeypatch.setenv("GITHUB_TOKEN", "t") + assert publish.main(["--coverage", str(tmp_path / "none.json"), "--diff", str(tmp_path / "diff-cover.json")]) == 1 + assert "none.json" in capsys.readouterr().err diff --git a/engineering-docs/development/unit-tests.md b/engineering-docs/development/unit-tests.md index be1afc81..9126e306 100644 --- a/engineering-docs/development/unit-tests.md +++ b/engineering-docs/development/unit-tests.md @@ -28,6 +28,13 @@ unit suite; the heavier suites are chosen by marker, never by accident. The `flaky` marker runs a test for visibility with a temporarily non-blocking result; the other markers belong to the heavier suites. +On a pull request the hosted workflow also writes both coverage figures, +changed lines covered and the whole package, into the pull request's +description between two marker comments, through +`scripts/publish_coverage_numbers_to_pr.py`; a merge that takes the +description as its message carries them into `main`'s history. The block is +replaced on every run and the author's text around it is never touched. + The hosted `tests.yml` workflow selects the existing serial unit suite when runtime, test, build or unclassified inputs change. It runs no Docker. Planning/status-only PRs skip heavy jobs; website inputs run the website's diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 56bec76e..d4d4ed18 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-03; unit-test conventions slice delivered for the owner's merge; 0.3.1 queue preserved +State: active 2026-11-04; PR #335 merged at 650e2be3; coverage-numbers slice delivered for the owner's merge; 0.3.1 queue preserved Definition read: WORKFLOW.md@d2ccbbe43dfa, WORKFLOW-LOCAL.md@65501b3407db @@ -12,10 +12,36 @@ Integration target: `main` Delivery method: ordinary maintenance PRs to `main`; owner merges. No records-only PR. The 0.3.0 release is published; website production promotion remains owner-operated. -Branch association: `ws-maintenance/test-conventions`, from `ws-maintenance/0.3.1-preparation` merged with main b3f10b7d, carrying the 0.3.1 preparation records to main with this slice; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical +Branch association: `ws-maintenance/coverage-in-pr` from main 650e2be3; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` +## Coverage numbers in the pull request — 2026-11-04 + +The owner merged #335 at 650e2be3 and asked for the next slice from the +2026-11-03 question: the diff coverage and the overall coverage in the pull +request's summary, and later in the merge commit's detail. CI already +computed both, the overall figure into the job summary and diff-cover's +report into an artifact and annotations; nothing reached the pull request. + +Delivered on `ws-maintenance/coverage-in-pr` as +[PR #336](https://github.com/ccozianu/devcapsule/pull/336) to `main`: +`scripts/publish_coverage_numbers_to_pr.py` reads `coverage.json` and +`diff-cover.json`, renders one block between `` +and ``, and replaces that block in the pull +request's description through the REST API, appending it when absent; the +author's text is never touched. The pytest job gains `pull-requests: write` +and runs the step on pull requests after diff coverage. Its tests are the +third mirror file, 9 cases in triple form. The merge commit part needs no +code: the owner sets the repository's default merge commit message to the +pull request's title and description, and the block travels into `main`'s +history as it stands at merge time. The owner set it from the command line +the same day; verified through the API: `merge_commit_title` PR_TITLE, +`merge_commit_message` PR_BODY. Recorded under *Integration Method* in +WORKFLOW-LOCAL.md. The first run on #336 spliced the block into prose that +quoted the markers and reported 100% of zero measured lines; both fixed at +87bba34e, the second run appended the block correctly. + ## Unit-test conventions — 2026-11-03 The owner resumed from travel and ran `nox -s build` in the dogfood capsule: