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.

95 lines
3.1 KiB

  1. # Contributing
  2. Welcome to the Python Keycloak contributing guidelines. We are all more than happy to receive
  3. any contributions to the repository and want to thank you in advance for your contributions!
  4. This document outlines the process and the guidelines on how contributions work for this repository.
  5. ## Setting up the dev environment
  6. The development environment is mainly up to the developer. Our recommendations are to create a python
  7. virtual environment and install the necessary requirements. Example
  8. ```sh
  9. # Install and upgrade pip & poetry
  10. python -m pip install --upgrade pip poetry
  11. # Create virtualenv
  12. python -m poetry env use <PATH_TO_PYTHON_VERSION>
  13. # install package dependencies including dev dependencies
  14. python -m poetry install
  15. # Activate virtualenv
  16. python -m poetry shell
  17. ```
  18. ## Running checks and tests
  19. We're utilizing `tox` for most of the testing workflows. However we also have an external dependency on `docker`.
  20. We're using docker to spin up a local keycloak instance which we run our test cases against. This is to avoid
  21. a lot of unnecessary mocking and yet have immediate feedback from the actual Keycloak instance. All of the setup
  22. is done for you with the tox environments, all you need is to have both tox and docker installed
  23. (`tox` is included in the `dev-requirements.txt`).
  24. To run the unit tests, simply run
  25. ```sh
  26. tox -e tests
  27. ```
  28. The project is also adhering to strict linting (flake8) and formatting (black + isort). You can always check that
  29. your code changes adhere to the format by running
  30. ```sh
  31. tox -e check
  32. ```
  33. If the check fails, you'll see an error message specifying what went wrong. To simplify things, you can also run
  34. ```sh
  35. tox -e apply-check
  36. ```
  37. which will apply isort and black formatting for you in the repository. The flake8 problems however need to be resolved
  38. manually by the developer.
  39. Additionally we require that the documentation pages are built without warnings. This check is also run via tox, using
  40. the command
  41. ```sh
  42. tox -e docs
  43. ```
  44. The check is also run in the CICD pipelines. We require that the documentation pages built from the code docstrings
  45. do not create visually "bad" pages.
  46. ## Conventional commits
  47. Commits to this project must adhere to the [Conventional Commits
  48. specification](https://www.conventionalcommits.org/en/v1.0.0/) that will allow
  49. us to automate version bumps and changelog entry creation.
  50. After cloning this repository, you must install the pre-commit hook for
  51. conventional commits (this is included in the `dev-requirements.txt`)
  52. ```sh
  53. # Create virtualenv
  54. python -m poetry env use <PATH_TO_PYTHON_VERSION>
  55. # Activate virtualenv
  56. python -m poetry shell
  57. pre-commit install --install-hooks -t pre-commit -t pre-push -t commit-msg
  58. ```
  59. ## How to contribute
  60. 1. Fork this repository, develop and test your changes
  61. 2. Make sure that your changes do not decrease the test coverage
  62. 3. Make sure your commits follow the conventional commits
  63. 4. Submit a pull request
  64. ## How to release
  65. The CICD pipelines are set up for the repository. When a PR is merged, a new version of the library
  66. will be automatically deployed to the PyPi server, meaning you'll be able to see your changes immediately.