Devenez un·e contributeur·ice

Prérequis

Flower utilise pyproject.toml pour gérer les dépendances et configurer les outils de développement (lesquels le supportent). uv est utilisé pour la gestion des dépendances, la construction et les flux de publication.

Setup de la machine

Preliminaries

Certaines dépendances système sont nécessaires.

Pour macOS

  • Installez homebrew. N’oubliez pas les actions post-installation pour ajouter brew à votre chemin de recherche.

  • Installez xz (pour installer différentes versions Python) et pandoc pour construire les documents :

    $ brew install xz pandoc

Pour Ubuntu

Assurez-vous que votre système (Ubuntu 22.04+) est à jour, et que vous avez tous les paquets nécessaires :

$ apt update
$ apt install build-essential zlib1g-dev libssl-dev libsqlite3-dev \
              libreadline-dev libbz2-dev libffi-dev liblzma-dev pandoc

Créez l’environnement de développement Flower

  1. Clônez le Flower repository depuis GitHub :

    $ git clone git@github.com:flwrlabs/flower.git
$ cd flower

  2. Installez uv en suivant les uv installation instructions.

  3. Initialisez l’environnement de développement du framework :

    $ ./dev/bootstrap.sh

    Le script d’initialisation crée framework/.venv à l’aide de la version Python fixée par le référentiel. Passer une version Python en tant qu’argument est le premier argument pour utiliser une autre :

    $ ./dev/bootstrap.sh 3.11.14

Scripts pratiques

Le référentiel Flower contient un certain nombre de scripts de commodité pour rendre les tâches de développement récurrentes plus faciles et moins sujettes à erreurs. Voir le sous-répertoire /dev pour une liste complète. Les scripts suivants sont parmi les plus importants :

Compiler les définitions ProtoBuf

$ ./framework/dev/protoc.sh

Formatter le code

$ ./framework/dev/format.sh

Vérifier le format et tester le code

$ ./framework/dev/test.sh

Ajoutez un hook pré-commit

Les développeurs peuvent intégrer un hook pré-commit dans leur workflow en utilisant la bibliothèque pre-commit. Le hook pré-commit est configuré pour exécuter deux opérations principales : les scripts ./framework/dev/format.sh et ./framework/dev/test.sh.

Il existe plusieurs façons dont les développeurs peuvent utiliser cela :

  1. Installez le hook pré-commit dans votre répertoire git local en simplement exécutant :

    $ pre-commit install

    • Chaque git commit déclenchera l’exécution des scripts de mise en forme et de vérification/test.

    • Si vous êtes pressé, sautez la mise en garde à l’aide de --no-verify avec le commande git commit.

      $ git commit --no-verify -m "Add new feature"

  2. Pour les développeurs qui préfèrent ne pas installer l’hook de manière permanente, il est possible d’exécuter une vérification unique avant de commiter des modifications en utilisant la commande suivante :

    $ pre-commit run --all-files

    Cela exécute les contrôles et tests de mise en forme et de vérification sur tous les fichiers sans modifier le comportement par défaut de git commit.

Exécuter les GitHub Actions (CI) localement

Les développeurs pourraient exécuter l’intégralité des workflows Actions GitHub sous leur environnement local en utilisant Act. Veuillez vous référer aux instructions d’installation dans le dépôt lié et exécutez la commande suivante dans le dossier principal du dépôt Flower cloné :

$ act

Le workflow par défaut de Flower sera exécuté en configurant les machines Docker requises en arrière plan.

Construire la version de sortie

Flower utilise uv pour construire des versions. La commande nécessaire est encapsulée dans un script simple :

$ ./framework/dev/build.sh

Les versions résultantes .whl et .tar.gz seront stockées dans le sous-répertoire ./framework/dist.

Construire la documentation

La documentation de Flower utilise Sphinx. Pour construire la documentation localement, exécutez le script suivant :

$ ./framework/dev/build-docs.sh

Cela générera une documentation HTML en ./framework/doc/build/html.

Notez que, pour construire la documentation localement, Pandoc doit être installé sur le système.