Participer au développement

Vous souhaitez mettre les mains dans le cambouis et devenir contributeurice de manière occasionnelle ou régulière ? D'abord merci ! Ensuite, n'hésitez pas à rejoindre le salon de discussion sur [matrix] pour pouvoir discuter de vos contributions et bénéficier de l'aide de la petite communauté de Hiboo.

Préparer un environnement de développement

Développer Hiboo nécessite de le déployer dans un environnement local. Pour cela, il faut :

installer les dépendances système
cloner le répertoire du code
installer les dépendances Python
installer les dépendances Node.js avec npm
compiler la documentation
compiler les ressources js et css avec Webpack
initialiser la base de données
lancer le serveur web Flask

Ces étapes peuvent être grandement facilitées par une conteneurisation de l'environnement, mais il est aussi possible de les effectuer à la main.

Déploiement local avec un nœud Podman ou Docker

Soit l'environnement suivant, où hiboo/ contiendra le code et tools/ les fichiers de déploiement des containers :

my-hiboo-dev-env/
├── hiboo/
│   ├── assets/
│   ├── babel.cfg
│   ├── CHANGELOG.md
│   ├── Dockerfile
│   ├── docs/
│   └── ...
└── tools/
    ├── compose.yml
    └── hiboo.env

Préparation des dossiers

mkdir my-hiboo-dev-env && cd my-hiboo-dev-env
git clone https://forge.tedomum.net/acides/hiboo.git
mkdir tools

Création du fichier `compose.yml`

Le nœud déploiera deux images : une Node pour compiler les assets dans un container hiboo-front, et une Python-Poetry pour installer Hiboo et faire tourner le serveur Flask dans un container hiboo-web :

services:
  hiboo-front:
    container_name: hiboo-front
    image: docker.io/node:22-alpine
    working_dir: /hiboo
    volumes:
      - '../hiboo:/hiboo'
    command: >
      /bin/sh -c "npm ci
      && node_modules/.bin/webpack-cli --watch"
  hiboo-web:
    container_name: hiboo-web
    image: docker.io/acidrain/python-poetry:3.12-slim
    depends_on:
      - hiboo-front
    working_dir: /hiboo
    volumes:
      - '../hiboo:/hiboo'
      - '.:/tools'
    env_file: 'hiboo.env'
    ports:
      - 5000:5000 # Flask server
      - 8000:8000 # If you need to serve Mkdocs-material
    command: >
      /bin/sh -c "apt update
      && apt install -y xmlsec1
      && poetry install --with dev,docs
      && poetry run mkdocs build -f docs/config/fr.yml
      && poetry run mkdocs build -f docs/config/en.yml
      && poetry run flask run --host '::' --reload"

Création du fichier `hiboo.env`

Trois variables suffisent à ce stade. Pour voir toutes les variables utilisables, consulter la documentation admin.

FLASK_APP=hiboo
DEBUG=false
SQLALCHEMY_DATABASE_URI=sqlite:////tools/hiboo.db

Lancement du nœud

# avec Docker
cd tools
docker compose up -d

# avec Podman
cd tools
podman compose up -d

Et voilà ! Hiboo sera accessible sur http://localhost:5000.

Déploiement local manuel sur Debian avec Poetry

Installation des dépendances système et de Poetry

apt install python3 python3-dev pkg-config nodejs npm curl xmlsec1
curl -sSL https://install.python-poetry.org | python3 -

Installation de Hiboo

Cloner le code source depuis la branche dev de la forge de Hiboo puis installer les dépendances :

git clone https://forge.tedomum.net/acides/hiboo.git
poetry install --with dev

Installation des dépendances Node.js et compilation des assets

npm ci
./node_modules/.bin/webpack-cli

Si vous prévoyez de toucher au js ou au css, vous pouvez laisser Webpack surveiller les changements et les compiler à la volée :

./node_modules/.bin/webpack-cli --watch

Compilation de la documentation intégrée

export FLASK_APP=hiboo
poetry run mkdocs build -f docs/config/en.yml
poetry run mkdocs build -f docs/config/fr.yml

Initialisation de la base de données

export FLASK_APP=hiboo
poetry run flask db upgrade

Lancement du serveur web

poetry run flask run --reload

Note : Pour lancer les tâches de fond (par exemple pour simuler des actions sur des profils), on peut lancer :

poetry run flask tasks loop

Lignes directrices

La forge git

Hiboo est développé sur la forge GitLab de Tedomum. Trois branches sont protégées :

la branche dev est la branche par défaut où le code est poussé lorsqu'il est prêt,
la branche main est la branche de publication : on y pousse le code uniquement lorsqu'une nouvelle version de Hiboo est prête.
la branche pages est utilisée pour la documentation autonome compilée avec Mike.

Note : Pour contribuer à Hiboo, il faut donc ouvrir un compte sur auth.tedomum.net afin d'avoir accès à la forge !

Tickets et Merge requests

Une fois l'environnement de développement installé, il n'y a plus qu'à coder ! Contribuer au développement implique de se coordonner avec les autres contributeurices. Pour cela, il faut respecter quelques règles de base :

Lorsqu'on souhaite s'emparer d'un sujet (bug à corriger, amélioration...), il faut vérifier si un ticket existe sur la forge, et sinon en créer un.
Lorsqu'on a des modifications du code à proposer, il faut créer une branche dédiée sur git puis une merge request sur la forge.

Tip : la création d'une branche et l'ouverture d'une merge request associée sont deux étapes qui peuvent être réalisées automatiquement depuis le ticket sur l'interface de Gitlab, voir l'aide à ce propos.

Le ticket et la merge request sont deux espaces de discussion privilégiés pour discuter des contributions, mais en complément, il est tout à fait encouragé de venir en discuter sur le salon [matrix] dédié.

Conventional commits

Pour que l'historique du développement soit le plus clair possible, il est demandé d'utiliser la syntaxe Conventional commits. Cependant, à l'intérieur d'une branche de développement, on peut déroger à cette règle dans la mesure où par défaut, les commits seront fusionnés au moment du merge dans la branche dev. Dans ce cas, il est impératif de vérifier le message du commit avant le merge en cochant « Edit commit message » dans la merge request.

Tip : par défaut, le message de commit d'une merge request est le titre de celle-ci. On peut donc intituler la merge request en conventionnal commit pour gagner du temps.

Références importantes

Dépendances Python

Les dépendances Python de Hiboo, déclarées dans le fichier pyproject.toml, sont gérées avec Poetry, un utilitaire de gestion et de traçabilité des dépendances.

Si vos contributions nécessitent de modifier les dépendances du projet et que vous n'êtes pas familiarisé·e avec Poetry, merci de consulter sa documentation.

Framework web

Le cœur du réacteur de Hiboo, c'est-à-dire tout le code qui en fait une application web (routes, vues, templates HTML), est conçu grâce au framework Flask.

Avant de toucher à cette partie du code (c'est-à-dire à la majorité de ce qui réside dans le dossier hiboo/), il est nécessaire de comprendre les bases du fonctionnement de Flask en consultant sa documentation.

Base de donnée

La relation entre l'application et la base de donnée est encadrée par les librairies SQLalchemy et Flask-SQLalchemy. Ces librairies sont incontournables dès qu'on souhaite effectuer la moindre requête :

En cas de modification de la structure de la base de donnée (nouvelle table, nouvelle colonne etc.), il est nécessaire de générer un fichier de migration pour permettre aux instances de Hiboo de mettre à jour leurs bases de données le moment venu. Pour générer ces fichiers, on utilise indirectement Alembic avec Flask-Migrate (en exécutant flask db migrate) :

Front-end

Les modèles HTML permettant de construire la partie visuelle de l'application sont présent dans les répertoires templates du code. Leur contenu utilise la syntaxe du moteur Jinja2 afin d'interagir dynamiquement avec Flask :

Les fichiers css et javascript sont stockés dans le dossier assets/, sachant que la majorité de la feuille de style de Hiboo est fournie par la librairie Bootstrap. Pour éviter de la compilation et de la complexité, celle-ci est obtenue par l'utilitaire Bootstrap-Flask :

Pour compiler le css et le javascript, on utilise Webpack.

Documentation

La documentation de l'application est une partie essentielle de Hiboo. Pour qu'elle reste pertinente, il faut toujours veiller à ce qu'elle soit à jour. En cas de suppression, de modification ou d'ajout d'une fonctionnalité dans Hiboo, il faut donc toujours veiller à la documenter. Pour cela, voir la section relative à la documentation.

Traduction

En cas de manipulation de textes ayant vocation à s'afficher sur l'interface web, il faut veiller à ce que les fichiers de traduction restent à jour pour que les personnes souhaitant traduire Hiboo puissent travailler sur une version propre. Pour cela, voir la section traduction.