Guidelines pour les contributions

Contribution au workflow, canaux de support et directives de développement.

Tâche

Discussion

Si vous avez une question, recherchez une aide interactive pour dépanner ou souhaitez discuter avec d’autres utilisateurs Patroni, rejoignez-nous sur le canal #patroni dans PostgreSQL Slack .

Signalement de bogues

Avant de signaler un bogue, assurez-vous d’en reproduire l’incident avec la dernière version de Patroni ! Veuillez également vérifier soigneusement si le problème n’existe pas déjà dans notre Suivi des problèmes .

Exécution des tests

Conditions requises pour exécuter les tests behave :

Les paquets PostgreSQL incluant les modules contrib doivent être installés.
Les binaires PostgreSQL doivent être disponibles dans votre PATH. Vous devrez peut-être les ajouter au chemin en utilisant quelque chose comme PATH=/usr/lib/postgresql/11/bin:\$PATH python -m behave.
Si vous souhaitez effectuer des tests avec des DCS externes (par exemple, etcd, Consul ou Zookeeper), vous devrez installer les paquets correspondants et faire fonctionner les services associés, qui doivent accepter les connexions non chiffrées/non protégées sur localhost et le port par défaut. Dans le cas d’Etcd ou de Consul, le jeu de tests behave peut les démarrer s’ils sont disponibles dans le PATH.

Installer les dépendances :

# You may want to use Virtualenv or specify pip3.
pip install -r requirements.txt
pip install -r requirements.dev.txt

Une fois toutes les dépendances installées, vous pouvez exécuter les différentes suites de tests :

# You may want to use Virtualenv or specify python3.

# Run flake8 to check syntax and formatting:
python setup.py flake8

# Run the pytest suite in tests/:
python setup.py test

# Moreover, you may want to run tests in different scopes for debugging purposes,
# the -s option include print output during test execution.
# Tests in pytest typically follow the pattern: FILEPATH::CLASSNAME::TESTNAME.
pytest -s tests/test_api.py
pytest -s tests/test_api.py::TestRestApiHandler
pytest -s tests/test_api.py::TestRestApiHandler::test_do_GET

# Run the behave (https://behave.readthedocs.io/en/latest/) test suite in features/;
# modify DCS as desired (raft has no dependencies so is the easiest to start with):
DCS=raft python -m behave

Test avec tox

Pour exécuter les tests tox, vous devez installer une seule dépendance (en plus de Python).

pip install tox>=4

Si vous souhaitez exécuter les tests behave, vous devez également disposer de Docker installé.

La configuration Tox dans tox.ini dispose d’« environments » permettant d’exécuter les tâches suivantes :

lint : analyse de code Python avec flake8
test : tests unitaires pour tous les interpréteurs Python disponibles avec pytest, génération de rapports XML ou HTML si un TTY est détecté
dep : détection des conflits de dépendances de paquets à l’aide de pipdeptree
type : vérification statique des types avec pyright
black : formatage du code avec black
docker-build : construction de l’image Docker utilisée pour l’environnement behave
docker-cmd : exécution d’une commande arbitraire avec l’image précédente
docker-behave-etcd : exécution de tox pour les tests behave avec l’image précédente
py*behave : exécution de behave avec les interpréteurs Python disponibles (sans Docker, bien que ce soit ce qui soit appelé à l’intérieur des conteneurs Docker)
docs : génération de la documentation avec sphinx

Exécution de tox

Pour exécuter la liste d’environnements par défaut (dep, lint, test et docs), exécutez simplement :

tox

Les variables d’environnement test peuvent être exécutées avec l’étiquette `test` :

tox -m test

Les tests Docker behave peuvent être exécutés avec l’étiquette `behave` :

tox -m behave

De même, docs porte l’étiquette docs.

Tous les autres environnements peuvent être exécutés avec leurs noms respectifs :

tox -e lint
tox -e py39-test-lin

Il est également possible de sélectionner des listes d’environnement partielles à l’aide de factors. Par exemple, si vous souhaitez exécuter toutes les environnements pour Python 3.10 :

tox -f py310

Cela équivaut à exécuter tous les environnements listés ci-dessous :

$ tox -l -f py310
py310-test-lin
py310-test-mac
py310-test-win
py310-type-lin
py310-type-mac
py310-type-win
py310-behave-etcd-lin
py310-behave-etcd-win
py310-behave-etcd-mac

Vous pouvez lister toutes les combinaisons d’environnements configurées avec tox (≥ v4) comme suit

tox l

Les variables d’environnement test et docs tenteront d’ouvrir les fichiers de sortie HTML une fois la tâche terminée, si tox est exécuté depuis un terminal actif. Cette fonction est destinée à faciliter le travail du développeur exécutant cet environnement localement. Elle tentera d’exécuter open sur macOS et xdg-open sur Linux. Pour utiliser une commande différente, définissez la variable d’environnement OPEN_CMD avec le nom ou le chemin de la commande. Si cette étape échoue, cela n’empêchera pas l’exécution globale de la tâche. Pour désactiver cette fonctionnalité, définissez la variable d’environnement OPEN_CMD sur la commande no-op :.

OPEN_CMD=: tox -m docs

Tests Behave

Les tests Behave avec -m behave construiront des images Docker basées sur les versions 11 à 16 de PG_MAJOR, puis exécuteront tous les tests Behave. Cette opération peut prendre beaucoup de temps, il est donc recommandé de limiter la portée à une version spécifique de PostgreSQL ou à un ensemble spécifique de fonctionnalités ou d’étapes.

Pour spécifier la version de postgres, indiquez le nom complet de l’environnement de build de l’image dépendante que vous souhaitez utiliser, suivi du nom de l’environnement behave. Par exemple, pour utiliser Postgres 14 :

tox -e pg14-docker-build,pg14-docker-behave-etcd-lin

Si, en revanche, vous souhaitez tester une fonctionnalité spécifique, vous pouvez passer des arguments positionnels à behave. Cela exécutera la scénario de test de fonctionnalité watchdog behave avec toutes les versions de Postgres.

tox -m behave -- features/watchdog.feature

Bien sûr, vous pouvez combiner les deux.

Contribution d’une demande de fusion

Fork le dépôt, développez et testez vos modifications de code.
Mettez à jour la documentation utilisateur.
Soumettez une requête de fusion avec une description claire de l’objectif des modifications. Liez une issue existante si nécessaire.

Vous recevrez un retour sur votre demande de tirage dès que possible.

Bon hacking avec Patroni ;-)