Contributing
Note
Linguard is and will always be open source.
You may contribute by opening new issues, commenting on existent ones and creating pull requests with new features and bugfixes. Any help is welcome, just make sure you read the following sections, which will guide you to set up the development environment.
Git flow
You should never work directly on the main
branch. This branch is only used to gather new features and bugfixes previously merged to the dev
branch and publish them in a single package. In other words, its purpose is to release new versions of Linguard.
Hence, the dev
branch should always be your starting point and the target of your pull requests.
git clone https://github.com/joseantmazonsb/linguard.git
cd linguard
git checkout dev
Requirements
You will need to install the following Linux packages:
sudo iproute2 python3 python3-venv wireguard iptables libpcre3 libpcre3-dev uwsgi uwsgi-plugin-python3
Dependency management
Poetry is used to handle packaging and dependencies. You will need to install it before getting started to code:
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python3 -
Once you have checked out the repository, you'd install the python requirements this way:
poetry config virtualenvs.in-project true
poetry install
Then, you would only need to run poetry shell
and voilà, ready to code!
Note
Actually, you should always run poetry run pytest
before getting started to code in order to check
that everything's all right.
Configuration files
Linguard has a setup assistant and does not require you to have an existing configuration file in its working directory. Nonetheless, you may use your own existing file as long as it is valid and named linguard.yaml
.
As for the UWSGI configuration, Linguard provides a sample file (uwsgi.sample.yaml
) for you to play around with it. Just make sure you run UWSGI using a valid file!
Testing
PyTest and Coverage are used to test Linguard and generate coverage reports, which are uploaded to Codecov.
TDD is enforced. Make sure your code passes the existing tests and provide new ones to prove your new features/bugfixes actually work when making pull requests.
All tests should be anywhere under linguard/tests
, and you can run them all using Poetry:
poetry run pytest
You may as well generate a coverage report using poetry:
poetry run coverage run -m pytest && poetry run coverage report
Building
To build Linguard you may use the build.sh
script, which automatically generates a dist
folder containing a compressed file with all you need to publish a release.
Versioning
Linguard is adhered to Semantic Versioning.
All releases must follow the format {MAJOR}.{MINOR}.{PATCH}
, and git tags linked
to releases must follow the format v{MAJOR}.{MINOR}.{PATCH}
. Thus, release
1.0.0
would be linked to the v1.0.0
git tag.
CI/CD
Github Workflows are used to implement a CI/CD pipeline. When pull requests targeting the main
or dev
branches are opened, a series of tests will automatically be ran to ensure everything is working properly.
Warning
The main
branch is used to automatically deploy new releases, and should never be the target of external pull requests.