You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
104 lines
3.4 KiB
104 lines
3.4 KiB
.. _contributing:
|
|
|
|
The Contributor Guide
|
|
========================
|
|
|
|
Welcome to the Python Keycloak contributing guidelines. We are all more than happy to receive
|
|
any contributions to the repository and want to thank you in advance for your contributions!
|
|
This document outlines the process and the guidelines on how contributions work for this repository.
|
|
|
|
Setting up the dev environment
|
|
-------------------------------
|
|
|
|
The development environment is mainly up to the developer. Our recommendations are to create a python
|
|
virtual environment and install the necessary requirements. Example
|
|
|
|
.. code-block:: console
|
|
|
|
# Install and upgrade pip & poetry
|
|
python -m pip install --upgrade pip poetry
|
|
|
|
# Create virtualenv
|
|
python -m poetry env use <PATH_TO_PYTHON_VERSION>
|
|
|
|
# install package dependencies including dev dependencies
|
|
python -m poetry install
|
|
|
|
# Activate virtualenv
|
|
python -m poetry shell
|
|
|
|
Running checks and tests
|
|
---------------------------
|
|
|
|
We're utilizing `tox` for most of the testing workflows. However we also have an external dependency on `docker`.
|
|
We're using docker to spin up a local keycloak instance which we run our test cases against. This is to avoid
|
|
a lot of unnecessary mocking and yet have immediate feedback from the actual Keycloak instance. All of the setup
|
|
is done for you with the tox environments, all you need is to have both tox and docker installed
|
|
(`tox` is included in the `dev-requirements.txt`).
|
|
|
|
To run the unit tests, simply run
|
|
|
|
.. code-block:: console
|
|
|
|
tox -e tests
|
|
|
|
The project is also adhering to strict linting (flake8) and formatting (black + isort). You can always check that
|
|
your code changes adhere to the format by running
|
|
|
|
.. code-block:: console
|
|
|
|
tox -e check
|
|
|
|
If the check fails, you'll see an error message specifying what went wrong. To simplify things, you can also run
|
|
|
|
.. code-block:: console
|
|
|
|
tox -e apply-check
|
|
|
|
which will apply isort and black formatting for you in the repository. The flake8 problems however need to be resolved
|
|
manually by the developer.
|
|
|
|
Additionally we require that the documentation pages are built without warnings. This check is also run via tox, using
|
|
the command
|
|
|
|
.. code-block:: console
|
|
|
|
tox -e docs
|
|
|
|
|
|
The check is also run in the CICD pipelines. We require that the documentation pages built from the code docstrings
|
|
do not create visually "bad" pages.
|
|
|
|
Conventional commits
|
|
----------------------
|
|
|
|
Commits to this project must adhere to the [Conventional Commits
|
|
specification](https://www.conventionalcommits.org/en/v1.0.0/) that will allow
|
|
us to automate version bumps and changelog entry creation.
|
|
|
|
After cloning this repository, you must install the pre-commit hook for
|
|
conventional commits (this is included in the `dev-requirements.txt`)
|
|
|
|
.. code-block:: console
|
|
|
|
# Create virtualenv
|
|
python -m poetry env use <PATH_TO_PYTHON_VERSION>
|
|
|
|
# Activate virtualenv
|
|
python -m poetry shell
|
|
|
|
pre-commit install --install-hooks -t pre-commit -t pre-push -t commit-msg
|
|
|
|
How to contribute
|
|
-------------------
|
|
|
|
1. Fork this repository, develop and test your changes
|
|
2. Make sure that your changes do not decrease the test coverage
|
|
3. Make sure you're commits follow the conventional commits
|
|
4. Submit a pull request
|
|
|
|
How to release
|
|
-------------------
|
|
|
|
The CICD pipelines are set up for the repository. When a PR is merged, a new version of the library
|
|
will be automatically deployed to the PyPi server, meaning you'll be able to see your changes immediately.
|