docs: create a CONTRIBUTING guide

CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# 🔧 Contributing
+
+<!-- TOC start (generated with https://github.com/derlin/bitdowntoc) -->
+
+- [Prerequisites](#prerequisites)
+- [Setting up the environment](#setting-up-the-environment)
+- [Running checks and tests](#running-checks-and-tests)
+- [About commits](#about-commits)
+- [How to contribute](#how-to-contribute)
+
+<!-- TOC end -->
+
+## Prerequisites
+
+Ensure you have the following available on your machine:
+
+- Python
+- Docker
+
+## Setting up the environment
+
+To work on this library locally, install the library in edit mode along with the dev dependencies:
+
+```bash
+# Use .[dev,test] to also install pytest and related libraries
+pip install -e '.[dev]'
+```
+
+To spawn the Keycloak Test Server, use the docker-compose.yml (done automatically when running
+tests, see blow):
+```bash
+docker compose up --wait
+```
+
+The server is configured using the resources in `tests/realms` and is available at
+`http://localhost:9090`. If you need to change anything to the realms, ensure you persist your
+changes using `make export-realms`.
+
+## Running checks and tests
+
+A **Makefile** is available for all the usual development tasks. Use `help` to list the available
+commands:
+
+```bash
+make help
+```
+```text
+Build
+  build  Build the wheels and sdist.
+
+Development
+  lint   Run ruff to format and lint (inside docker).
+  test   Run tests with tox (inside docker).
+  mypy   Run mypy locally to check types.
+  export-realms  Export test realms after changes in Keycloak Test Server.
+```
+
+Note that `make test` automatically starts a Keycloak container if it isn't already running. You may
+have to stop it manually. The test server is configured using the resources in `tests/realms` and is
+available at `http://localhost:9090`. To start the Keycloak server yourself:
+
+```bash
+docker compose up --wait
+```
+
+You can run the tests directly using `pytest` for faster development, just ensure you installed the
+test dependencies (`pip install -e '.[dev,test]'`) and Keycloak is running.
+
+## About commits
+
+This repository adheres to the
+[Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) and requires
+[signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
+
+## 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. Create signed commits that follow the conventional commits specification
+4. Submit a pull request
+

README.md

@@ -30,7 +30,6 @@ the excellent [slumber](https://slumber.readthedocs.io/) library.
    * [Other ways of authenticating](#other-ways-of-authenticating)
 - [📡 Making calls](#-making-calls)
 - [💀 Exceptions](#-exceptions)
-- [🔧 Development](#-development)
 
 <!-- TOC end -->
 
@@ -299,48 +298,3 @@ HttpException(
     response='<requests.Response>',
 )
 ```
-
----
-
-## 🔧 Development
-
-Prerequisites:
-
-- Python
-- Docker
-
-To work on this library locally, install the library in edit mode along with the dev dependencies:
-
-```bash
-# Use .[dev,test] to also install pytest and related libraries
-pip install -e '.[dev]'
-```
-
-A **Makefile** is available for all the usual development tasks. Use help to list the available
-commands:
-
-```bash
-make help
-```
-```text
-Build
-  build  Build the wheels and sdist.
-
-Development
-  lint   Run ruff to format and lint (inside docker).
-  test   Run tests with tox (inside docker).
-  mypy   Run mypy locally to check types.
-  export-realms  Export test realms after changes in Keycloak Test Server.
-```
-
-Note that `make test` automatically starts a Keycloak container if it isn't already running. You may
-have to stop it manually. The test server is configured using the resources in `tests/realms` and is
-available at `http://localhost:9090`. To start the Keycloak server yourself:
-
-```bash
-docker compose up --wait
-```
-
-You can run the tests directly using `pytest` for faster development, just ensure you installed the
-test dependencies (`pip install -e '.[dev,test]'`) and Keycloak is running.
-