From e262990c689c6895a4724a7fd2c42412a8dca6a6 Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Sun, 16 Jun 2024 19:23:46 +0200 Subject: [PATCH] Tweak docs about test coverage and `git blame` --- docs/contribute.rst | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/contribute.rst b/docs/contribute.rst index 419ba80f..07cf998a 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -64,19 +64,26 @@ your bug fix or feature:: Now you can make changes to Pelican, its documentation, and/or other aspects of the project. -Setting up git blame --------------------- +Setting up ``git blame`` (optional) +----------------------------------- -``git blame`` annotates lines from a file with information about the pull request -that last modified it. Sweeping shallow changes (like formatting) can make that -information less useful, so we keep a list of such changes to be ignored. To set -that up in your repository:: +``git blame`` annotates lines in a file with information about the pull request +that last modified it. Sweeping shallow changes (like formatting) can make that +information less useful, so we keep a list of such changes to be ignored. Run the +following command to set this up in your repository, adding ``--global`` if you +want this setting to apply to all repositories:: git config blame.ignoreRevsFile .git-blame-ignore-revs -For more information, see here_. +As noted in a `useful article`_ about ``git blame``, there are other related +settings you may find to be beneficial:: -.. _here: https://www.michaelheap.com/git-ignore-rev/ + # Add `?` to any lines that have had a commit skipped using --ignore-rev + git config --global blame.markIgnoredLines true + # Add `*` to any lines that were added in a skipped commit and can not be attributed + git config --global blame.markUnblamableLines true + +.. _useful article: https://www.michaelheap.com/git-ignore-rev/ Running the test suite ---------------------- @@ -125,16 +132,17 @@ environments. Running a code coverage report ------------------------------ -The code is more likely to stay robust if it is tested. -coverage_ is a library that measures how much of the code is tested. -To run it:: +Code is more likely to stay robust if it is tested. Coverage_ is a library that +measures how much of the code is tested. To run it:: invoke coverage + +This will show overall coverage, coverage per file, and even line-by-line coverage. +There is also an HTML report available:: + open htmlcov/index.html -The HTML will show overall coverage, coverage per file, and even line-by-line coverage. - -.. _coverage: https://github.com/nedbat/coveragepy +.. _Coverage: https://github.com/nedbat/coveragepy Building the docs -----------------