Quality Assurance Checks

Note

This documentation page is aimed at developers who want to customize, change or extend the code of OpenWISP Utils in order to modify its behavior (e.g.: for personal or commercial purposes or to fix a bug, implement a new feature or contribute to the project in general).

If you aren't a developer and you are looking for information on how to use OpenWISP, please refer to:

This package contains some common QA checks that are used in the automated builds of different OpenWISP modules.

openwisp-qa-format

This shell script automatically formats Python and CSS code according to the OpenWISP coding style conventions.

It runs isort and black to format python code (these two dependencies are required and installed automatically when running pip install openwisp-utils[qa]).

The prettier programs is used to perform style checks on CSS and JS code, but it is optional: if prettier is not installed, the check(s) will be skipped.

openwisp-qa-check

Shell script to run the following quality assurance checks:

If a check requires a flag, it can be passed forward in the same way.

Usage example:

openwisp-qa-check --migration-path <path> --message <commit-message>

Any unneeded checks can be skipped by passing --skip-<check-name>

Usage example:

openwisp-qa-check --skip-isort

For backward compatibility csslinter and jslinter are skipped by default. To run them during QA checks pass arguments as follows.

Usage example:

# To activate csslinter
openwisp-qa-check --csslinter

# To activate jslinter
openwisp-qa-check --jslinter

You can do multiple checkmigrations by passing the arguments with space-delimited string.

For example, this multiple checkmigrations:

checkmigrations --migrations-to-ignore 3 \
        --migration-path ./openwisp_users/migrations/ || exit 1

checkmigrations --migrations-to-ignore 2 \
        --migration-path ./tests/testapp/migrations/ || exit 1

Can be changed with:

openwisp-qa-check --migrations-to-ignore "3 2" \
        --migration-path "./openwisp_users/migrations/ ./tests/testapp/migrations/"

checkmigrations

Ensures the latest migrations created have a human readable name.

We want to avoid having many migrations named like 0003_auto_20150410_3242.py.

This way we can reconstruct the evolution of our database schemas faster, with less efforts and hence less costs.

Usage example:

checkmigrations --migration-path ./django_freeradius/migrations/

Commit message checks

Ensures the last commit message follows our commit message style guidelines.

We want to keep the commit log readable, consistent and easy to scan in order to make it easy to analyze the history of our modules, which is also a very important activity when performing maintenance.

This check uses Commitizen with a custom OpenWISP Commitizen plugin. After staging changes to git, contributors can use Commitizen to create commit messages easily.

Instead of using:

git commit

Contributors can use the openwisp-commit shortcut:

openwisp-commit

This command interactively prompts for the commit prefix, title (optionally including the reference to a github issue) and a short description of the changes, and generates a commit message which follows the OpenWISP commit message conventions.

If you reference an issue in the title (e.g., [feature] Add support #123) but don't reference it in the body, the tool will automatically append Related to #123 to the commit message for you.

The following patterns are valid in the body: Fixes, Closes, Resolves, or Related to.

If you need to amend the last commit (e.g., to fix the commit message), use the --amend flag:

openwisp-commit --amend

To check whether your commit message follows the conventions, use:

openwisp-commit --check

This validates the latest commit message against the defined conventions and reports any formatting issues.

For advanced use cases, you can also use Commitizen directly:

cz -n cz_openwisp commit
cz -n cz_openwisp check --rev-range HEAD^!

checkendline

Ensures that a blank line is kept at the end of each file.

checkpendingmigrations

Ensures there django migrations are up to date and no new migrations need to be created.

It accepts an optional --migration-module flag indicating the django app name that should be passed to ./manage.py makemigrations, e.g.: ./manage.py makemigrations $MIGRATION_MODULE.

checkrst

Checks the syntax of all ReStructuredText files to ensure they can be published on Pypi or using python-sphinx.