From e726254a380f2a35a2fcf71143e96cb5987d8102 Mon Sep 17 00:00:00 2001 From: saurabh Date: Tue, 26 Aug 2025 00:18:42 +0530 Subject: Refs #36620 -- Added contributor documentation for code coverage reports. This was included in the original reverted patch: a89183e63844a937aacd3ddb73c4952ef869d2cc Follow-up to 26b0e2bb92caf2d16cabe455792350f20d6f42ca. --- .../writing-code/submitting-patches.txt | 3 ++ .../contributing/writing-code/unit-tests.txt | 43 ++++++++++++++++++++++ 2 files changed, 46 insertions(+) (limited to 'docs/internals/contributing/writing-code') diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index 841a2109dc..428acffba1 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -438,6 +438,9 @@ All code changes * If the change is backwards incompatible in any way, is there a note in the release notes (``docs/releases/A.B.txt``)? * Is Django's test suite passing? +* If there is a :ref:`code coverage report ` + comment on the pull request, have you reviewed the missing coverage in + context (considering database/platform-specific limitations)? * If the change affects the Django admin or rendered HTML output, has :ref:`accessibility testing ` been done? diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index cba4ba7397..f304970a29 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -394,6 +394,49 @@ settings file defines ``coverage_html`` as the output directory for the report and also excludes several directories not relevant to the results (test code or external code included in Django). +.. _code-coverage-on-pull-requests: + +Code coverage on pull requests +------------------------------ + +Django's continuous integration (CI) system automatically runs code coverage +analysis on pull requests and posts a comment with a diff coverage report. This +helps reviewers see which lines in the changed code are covered by tests. + +**What the coverage report shows:** + +The coverage report posted on pull requests uses `diff-cover`_ to analyze only +the lines that were changed or added in the PR. It shows: + +* Lines that are covered by tests (✓) +* Lines that are not covered by tests (✗) +* Lines that cannot be covered (e.g., comments, blank lines) + +.. _diff-cover: https://github.com/Bachmann1234/diff_cover + +**Important limitations:** + +When reviewing coverage reports on pull requests, keep these limitations in +mind: + +* **Database-specific code:** The CI coverage job runs tests using SQLite on + Windows. Code paths specific to other databases (PostgreSQL, MySQL, Oracle) + will appear as "not covered" even if database-specific tests exist. This is + expected and acceptable. + +* **Platform-specific code:** Similarly, code that only runs on certain + operating systems (Linux, macOS) will appear as not covered when run on + Windows. + +* **Coverage doesn't equal quality:** A line being "covered" only means it was + executed during tests. It doesn't guarantee the line is well-tested or that + all edge cases are handled. During review, assess test quality beyond just + coverage numbers. + + +Missing coverage should be considered a warning rather than a blocker and +should be evaluated in context. + .. _contrib-apps: Contrib apps -- cgit v1.3