/
CI Best Practices

CI Best Practices

Jan 30, 2019

Code Review

All patches that go into a project repo need to be code reviewed by someone other than the original author. Code review is a great way to both learn from others as well as improve code quality. Contribution to code review is highly recommended regardless of activity as a committer.

Below provides a simple checklist of common items that code reviewers should look out for (Patch submitters can use this to self-review as well to ensure that they are not hitting any of these):

General

  • Does the Git commit message sufficiently describes the change? (Refer to: https://chris.beams.io/posts/git-commit/)

  • Does the commit message have an ‘Issue: <someissue>’ in the footer and not in the subject line or body?

  • Are there any typos?

  • Are all code review comments addressed?

  • Is the code rebased onto the latest HEAD of the branch?

  • Does the code pull in any dependencies that might have license conflicts with this project’s license?

Code

  • Are imports alphabetical and sectioned off by stdlib, 3rdparty, and local?

  • Are functions / methods organized alphabetically? (or categorized alphabetically)

  • Does the change need unit tests? (Yes, it probably does!)

  • Does the change need documentation?

  • Does every function added have function docs? (javadoc, pydoc, whatever the language code docs is)

  • Does it pass linting?

  • Does the code cause backwards compatibility breakage? (If so it needs documentation)

Note

Refer to Google’s blog (google-blog-code-health) on effective code review.

Generic Linting (Coala)

Coala is a great tool for linting all languages. The easiest way to run Coala is with python-tox and requires Python 3 installed on the system:

tox -ecoala

Running Coala without Tox can come in handy for executing Coala in interactive mode. In this case, install Coala in a Python viritualenv. Use virtualenvwrapper as it makes it simple to manage local virtual environments.

Requirements

 

Install Coala

Note

Some distros have a package called coala available but do not confuse this package with python-coala which is an entirely different piece of software.

Using virtualenv (assuming virtualenvwrapper is available), install Coala:

mkvirtualenv --python=/usr/bin/python3 coala pip install coala coala-bears coala --help

For future usage of an existing virtualenv, activate as follows:

# Re-activate Coala virtualenv workon coala # Run the coala command coala --help

Set up Coala for a Project

Use python-tox to manage a Coala setup for any projects that require linting.

Requirements

Configure the project with a tox.ini and a .coafile file. Below are examples of .coafile and tox.ini as defined by lftools. Inside the tox.ini file the interesting bits are under [testenv:coala].

.coafile

[all]ignore=.tox/**, .git/**, .gitignore, .gitreview, .gitmodules, node_modules/**[all.Git]bears=GitCommitBearignore_length_regex=Signed-off-by, Also-by, Co-authored-by, http://, https://[all.Documentation]bears=WriteGoodLintBearfiles=docs/**/*.rst[all.MarkDown]bears=MarkdownBear,SpaceConsistencyBear,WriteGoodLintBearfiles=**.md, **.markdownuse_spaces=true[all.Python]bears=BanditBear, PEP8Bear, PyCommentedCodeBear, PyDocStyleBear, PyFlakesBear, PyImportSortBearfiles=*.py

tox.ini

[tox]minversion=1.6envlist= check-best-practices, check-hooks, coala, docs, docs-linkcheckskipsdist=true[testenv:check-best-practices]commands=python {toxinidir}/check-best-practices.py[testenv:check-hooks]deps=pre-commitcommands= pre-commit install pre-commit run --all-files[testenv:coala]basepython=python3deps= coala coala-bears nodeenvcommands= nodeenv -p npm install --global remark-cli remark-lint write-good python3 -m nltk.downloader punkt maxent_treebank_pos_tagger averaged_perceptron_tagger coala --non-interactive[testenv:docs]deps=-rrequirements.txtcommands= sphinx-build -j auto -W -b html -n -W -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html[testenv:docs-linkcheck]deps=-rrequirements.txtcommands=sphinx-build -j auto -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck

Jenkins Job Builder

Jenkins Job Builder Best Practices