116 lines
3.2 KiB
Markdown
116 lines
3.2 KiB
Markdown
# Contributing to check_patroni
|
|
|
|
Thanks for your interest in contributing to check_patroni.
|
|
|
|
## Clone Git Repository
|
|
|
|
Installation from the git repository:
|
|
|
|
```
|
|
$ git clone https://github.com/dalibo/check_patroni.git
|
|
$ cd check_patroni
|
|
```
|
|
|
|
Change the branch if necessary.
|
|
|
|
## Create Python Virtual Environment
|
|
|
|
You need a dedicated environment, install dependencies and then check_patroni
|
|
from the repo:
|
|
|
|
```
|
|
$ python3 -m venv .venv
|
|
$ . .venv/bin/activate
|
|
(.venv) $ pip3 install .[test]
|
|
(.venv) $ pip3 install -r requirements-dev.txt
|
|
(.venv) $ check_patroni
|
|
```
|
|
|
|
To quit this env and destroy it:
|
|
|
|
```
|
|
$ deactivate
|
|
$ rm -r .venv
|
|
```
|
|
|
|
## Development Environment
|
|
|
|
A vagrant file is available to create a icinga / opm / grafana stack and
|
|
install check_patroni. You can then add a server to the supervision and
|
|
watch the graphs in grafana. It's in the `vagrant` directory.
|
|
|
|
A vagrant file can be found in [this
|
|
repository](https://github.com/ioguix/vagrant-patroni) to generate a patroni/etcd
|
|
setup.
|
|
|
|
The `README.md` can be geneated with `./docs/make_readme.sh`.
|
|
|
|
## Executing Tests
|
|
|
|
Crafting repeatable tests using a live Patroni cluster can be intricate. To
|
|
simplify the development process, interactions with Patroni's API are
|
|
substituted with a mock function that yields an HTTP return code and a JSON
|
|
object outlining the cluster's status. The JSON files containing this
|
|
information are housed in the `./tests/json` directory.
|
|
|
|
An important consideration is that there is a potential drawback: if the JSON
|
|
data is incorrect or if modifications have been made to Patroni without
|
|
corresponding updates to the tests documented here, the tests might still pass
|
|
erroneously.
|
|
|
|
The tests are executed automatically for each PR using the ci (see
|
|
`.github/workflow/lint.yml` and `.github/workflow/tests.yml`).
|
|
|
|
Running the tests manually:
|
|
|
|
* Using patroni's nominal replica state of `streaming` (since v3.0.4):
|
|
|
|
```bash
|
|
pytest ./tests
|
|
```
|
|
|
|
* Using patroni's nominal replica state of `running` (before v3.0.4):
|
|
|
|
```bash
|
|
pytest --use-old-replica-state ./tests
|
|
```
|
|
|
|
* Using tox:
|
|
|
|
```bash
|
|
tox -e lint # mypy + flake8 + black + isort ° codespell
|
|
tox # pytests and "lint" tests for all supported version of python
|
|
tox -e py # pytests and "lint" tests for the default version of python
|
|
```
|
|
|
|
Please note that when dealing with any service that checks the state of a node
|
|
in patroni's `cluster` endpoint, the corresponding JSON test file must be added
|
|
in `./tests/tools.py`.
|
|
|
|
A bash script, `check_patroni.sh`, is provided to facilitate testing all
|
|
services on a Patroni endpoint (`./vagrant/check_patroni.sh`). It requires one
|
|
parameter: the endpoint URL that will be used as the argument for the
|
|
`-e/--endpoints` option of `check_patroni`. This script essentially compiles a
|
|
list of service calls and executes them sequentially in a bash script. It
|
|
creates a state file in the directory from which you run the script.
|
|
|
|
Here's an example usage:
|
|
|
|
```bash
|
|
./vagrant/check_patroni.sh http://10.20.30.51:8008
|
|
```
|
|
|
|
## Release
|
|
|
|
Update the Changelog.
|
|
|
|
The package is generated and uploaded to pypi when a `v*` tag is created (see
|
|
`.github/workflow/publish.yml`).
|
|
|
|
Alternatively, the release can be done manually with:
|
|
|
|
```
|
|
tox -e build
|
|
tox -e upload
|
|
```
|