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.
Lancement du nœud
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 :
Installation des dépendances Node.js et compilation des assets
Si vous prévoyez de toucher au js ou au css, vous pouvez laisser Webpack surveiller les changements et les compiler à la volée :
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
Lancement du serveur web
Note : Pour lancer les tâches de fond (par exemple pour simuler des actions sur des profils), on peut lancer :
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.