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 -----------------