CI: Add automatic code coverage references

.github/workflows/coverage.yml

@@ -163,6 +163,8 @@ jobs:
               grep -E "(lines|branches)\.*:" ${{ github.workspace }}/make-coverage-report.log | sed "s/\.*:/:/" >> notification/body.txt || true
               echo "</pre>" >> notification/body.txt
               echo "Report: [${{ github.run_id }}](https://${{ github.repository_owner }}.github.io/verilator/coverage-reports/${{ github.run_id }}/index.html)" >> notification/body.txt
+              echo "" >> notification/body.txt
+              echo "Please get to 100% line coverage, and understand all branches; see https://github.com/verilator/verilator/blob/master/docs/internals.rst#code-coverage-results" >> notification/body.txt
             else
               echo "Patch contains no code changes" >> notification/body.txt
             fi

docs/internals.rst

@@ -1701,7 +1701,7 @@ can have significant variance. Experience shows that a ~20% time difference
 can be reliably measured on GitHub hosted runners, and smaller differences
 are noticeable over a few days of reruns as trends emerge from the noise.
 
-Code coverage
+Code Coverage
 -------------
 
 Code coverage for developing Verilator itself can be collected using
@@ -1750,6 +1750,25 @@ example, to see coverage of changes compared to upstream, use:
 
    make coverage-view COVERAGE_BASE=origin/master
 
+
+Code Coverage Results
+---------------------
+
+When code coverage is complete, line coverage should be at 100%. Branch
+coverage is not required to be at 100%, but all uncovered branches should
+be understood as to why.
+
+For lines which are impossible, use ``// LCOV_EXCL_LINE``, or ``//
+LCOV_EXCL_START`` and ``// LCOV_EXCL_STOP`` regions.
+
+For branches which are impossible, use the ``VL_UNCOVERABLE(condition)``
+macro around uncoverable conditions, otherwise use ``//
+LCOV_EXCL_BR_LINE``.
+
+The assertions ``UASSERT`` and similar are automatically excluded from
+coverage, and as such should not require exclusion meta comments.
+
+
 Fuzzing
 -------