Setting up a Development Environment¶
This document explains how to set up a devlopment environment for the CLAC project.
A note about Makefiles¶
CLAC includes a Makefile to simplify the devlopment process. This allows
commands to be run in a virtual environment without having to actually activate
the environment in your own shell. To support this on Windows (which is the
real outlier) and other systems at the same time, the WORKON_HOME environment
variable must be set, and must NOT contain backslashes. This means that on my
windows platforms, the virtualenv home directory must be set to D:/dev/venv
instead of D:\dev\venv
.
Cloning the project¶
To clone the project, please follow the steps below (after reading the whole section to understand exactly what impact it will have):
- Ensure you are cloning the correct project (i.e. cloning your fork instead of the project itself)
git clone https://github.com/<yourusername>/clac
make test
The make test
command will create a new virtual environment using the
current python interpreter as a base. The environment will be stored in
$WORKON_HOME/clac
, and the full path to the executable will be written to a
file named .venv
at the root of the project.
Confirming your changes¶
In order to prevent destabilization of the project, all changes must pass CI checks without fail. Changes will not be accepted until this occurs. There are four checks which occur as of writing this:
- Unit testing through pytest
-
make test
- Code style/linting with pylint
-
make lint
- Static type analysis using mypy
-
make lint
must pass the pylint check first for make to work. - Building documentation powered by sphinx
-
make docs
If any one of these fails, your pull request will be rejected. If rejected, you must submit a patch to the pull request which resolves the issue.
Additionally, if your change is an enhancement or bugfix to the codebase, it must be accompanied by passing, coverage-proven unit tests. Changes without unit tests will not be accepted, but if you are unsure of how to unit test your changes, submit anyway and the project owner will help you to write effective unit tests for your change.
Working without make¶
If you cannot use make, or wish to setup your own environment in a different way, please follow the guide as-is, but referencing this section for alternative executions to mimic make’s functionality.
This section will be written with the assumption that you understand how to configure your desired environment and use it properly, and is being provided as a convenience. Additionally, all of these commands should be executed from the project root.
pip install
sections only need to be run once per environment.
- make install
pip install -e .
- make install-dev
pip install -e .[fulldev]
- make test
pip install -e .[test,cov] && pytest --cov clac tests && python -m coverage html
- make docs
pip install -e .[docs] && sphinx-build -M html docs/source docs/build
- make lint
pip install -e .[lint] && pylint clac && mypy clac