CONTRIBUTING.md

How to contribute

Dependencies

We use poetry to manage the dependencies. If you don't have poetry, you should install with make poetry-download.

To install dependencies and prepare pre-commit hooks you would need to run install command:

Linux

make install
make pre-commit-install

Windows

poetry run pre-commit install
pre-commit run --all-files

Preparing for a release

Linux

export PATH="$HOME/.poetry/bin:$PATH"
make install
make pre-commit-install
pre-commit run --all-files
make test && make coverage && make check-codestyle && make mypy && make check-safety && make extrabadges
pre-commit run --all-files

Windows

1. Install Poetry:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

2. Find the poetry installation directory:

C:\Users\YourUsername\AppData\Roaming\Python\Scripts
C:\Users\YourUsername\AppData\Local\Programs\Python\PythonXX\Scripts (where XX is the Python version)

3. Add the correct Path to PATH:

$env:PATH = "C:\Users\YourUsername\AppData\Roaming\Python\Scripts;" + $env:PATH

4. Verify poetry installation:

poetry --version

5. Create and activate a new virtual environment:

python -m venv .venv
.\.venv\Scripts\activate

5. Install required libraries:

poetry lock -n; poetry export --without-hashes > requirements.txt
poetry install -n

6. Type check with mypy

poetry run mypy --install-types --non-interactive pycvcqv/ tests/

7. Unit tests and coverage

poetry run pytest --cov-report html --cov pycvcqv tests/
poetry run coverage-badge -o assets/images/coverage.svg -f

8. Lint

poetry run pylint pycvcqv tests

9. Code-style check

poetry run pyupgrade --exit-zero-even-if-changed --py37-plus
poetry run isort --diff --check-only --settings-path pyproject.toml ./
poetry run black --diff --check --config pyproject.toml ./
poetry run darglint --verbosity 2 pycvcqv tests
poetry run interrogate -v pycvcqv

10. Safety check

poetry check
poetry run safety check --policy-file safety_policy.yml
poetry run bandit -ll --configfile pyproject.toml --recursive pycvcqv tests

11. Code maintainability and complexity

.\.shell\maintainability.ps1
.\.shell\complexity.ps1

12. Creating badges data

.\.shell\badges.ps1

Upload code to GitHub

git pull
pre-commit run --all-files
git add .
git commit -m ":tada: Initial commit"
git push -u origin main

Documentation with jupyter-book

poetry run jupyter-book build .\assets\docs\pycvcqv

12. Upload to pypi (for maintainers)

pip install twine
pip install --upgrade build
python -m build
python -m twine upload --repository pycvcqv dist/*
git tag -a <tag_name> -m "<message>"
git push -u origin <tag_name>

Other help

You can contribute by spreading a word about this library. It would also be a huge contribution to write a short article on how you are using this project. You can also share your best practices with us.