Checkmate is a small program to generate human-readable checklists from
a given patch (or pull request). Leave CHECK
comments (that are the same
fashion as FIXME
or TODO
comments); then Checkmate detects when a diff
touches some code scopes having any CHECK
comments, and lists the checks.
It helps contributors and reviewers to remind matters that require attention when a part of the code is changed.
Let's say there's a dictionary, and we should update the manual when a key is added to or removed from it:
TARGET_LANGUAGES = {
# CHECK: Please update the manual on the project wiki when you add/remove
# a language.
'c': '*.c',
'java': '*.java',
'javascript': '*.js',
'python': '*.py',
}
The above example may be artificial, but suppose lines of the dictionary are lengthy. Such tasks should be done outside of the source code repository so that they cannot be automated by simply eliminating code duplicates. Contributors and reviewers altogether are easy to forget about such tasks.
To remind peers of such tasks, Checkmate detects CHECK
comments like the above
example when a relevant code block is touched and show peers a checklist.
How does Checkmate list only relevant checks to a diff? It currently doesn't have any language-specific algorithms, but only a language-agnostic heuristics on indented blocks.
Suppose the following diff:
diff --git a/langs.py b/langs.py
--- a/langs.py
+++ b/langs.py
@@ -5,6 +5,7 @@ TARGET_LANGUAGES = {
'c': '*.c',
'java': '*.java',
'javascript': '*.js',
+ 'haskell': '*.hs',
'python': '*.py',
}
Since it touched a code block with a CHECK
comment, Checkmate generates
the following checklist:
- Please update the manual on the project wiki when you add/remove a language.
Suppose a patch touches only code blocks without any CHECK
comments too, e.g.:
diff --git a/langs.py b/langs.py
--- a/langs.py
+++ b/langs.py
@@ -8,6 +8,7 @@ TARGET_LANGUAGES = {
'python': '*.py',
}
OTHER_DATA = {
# This code block is not relevant to TARGET_LANGUAGES.
+ 'haskell': '*.hs',
}
Since the touched block doesn't have any CHECK
comments, Checkmate generates
an empty checklist.
Note that it doesn't parse code's semantics, but only scans blocks through indentation. Even if a block is wrapped in curly braces without indentation, it isn't counted as a block.
Some checks may need to be listed for a whole directory. Checkmate recognizes
files named .check or CHECK in a directory and include checks in that to
the checklist if any file in the directory are changed. Its syntax is basically
a simple bullet list and a bullet can be *
/-
/+
/CHECK
or digits followed
by .
/)
, e.g.:
- Check 1
- Check 2
+ A plus sign too can be a bullet.
* An asterisk too.
1. Numbered-bullets also can be used.
2) A closing parenthesis as well can follow instead of a period.
CHECK: For consistency `CHECK` keyword also can be a bullet as well.
CHECK And a colon can be omitted.
Lines without any bullet is continued from previous line(s).
We provide an official Linux x86_64 binary for every release. See also
the latest release. Note that official binaries are distributed as
statically-linked standalone executable, and they aren't gzipped. Download and
give an +x
permission; then it's ready.
On the other platforms you can download and install using Haskell Cabal or Stack since source tarballs also are distributed on Hackage:
stack install checkmate
Note: if you experience an error like ConnectionFailure Network.BSD.getProtocolByName: does not exist (no such protocol name: tcp)
on Debian/Ubuntu Linux, try to install netbase package.
(Read this explanation for details.)
Since Checkmate usually is executed as a part of CI build, we show examples for widely-used CI services.
All examples assume the environment variables are defined:
-
GITHUB_TOKEN
contains the access token to leave comments on a corresponding GitHub repository. See also GitHub's official article about personal API tokens. -
CHECKMATE_DOWNLOAD_URL
contains the download link to the prebuilt binary of the latest release, i.e.:CHECKMATE_DOWNLOAD_URL=https://github.com/dahlia/checkmate/releases/download/0.4.1/checkmate-linux-x86_64
install:
- curl -L -o ~/bin/checkmate "$CHECKMATE_DOWNLOAD_URL"
- chmod +x ~/bin/checkmate
script:
- ~/bin/checkmate github-travis --token "$GITHUB_TOKEN"
dependencies:
post:
- curl -L -o ~/bin/checkmate "$CHECKMATE_DOWNLOAD_URL"
- chmod +x ~/bin/checkmate
test:
post:
- ~/bin/checkmate github-circle --token "$GITHUB_TOKEN"
You can run checkmate github
command with explicit arguments:
curl -L -o ~/bin/checkmate "$CHECKMATE_DOWNLOAD_URL"
chmod +x ~/bin/checkmate
# Suppose we're running a build of github.com/foo/bar/pull/123
~/bin/checkmate github \
--token "$GITHUB_TOKEN" \
--login foo \
--repo bar \
--pr 123
If you're using GitHub Enterprise on premise use --endpoint
option.
Further reading: checkmate github --help
.