Contribuer

Vous souhaitez contribuer ? Bienvenue, c’est ce qui participera à faire avancer Bénévalibre ! Sans toucher au code, il y a de nombreuses façons de contribuer :

Si vous voulez aller plus loin, de participer à cette documentation, reporter un problème ou une demande de fonctionnalité, voir contribuer au code, la suite devrait être faite pour vous. Nous avons tenté d’y aller progressivement en technicité, toute contribution pour rendre cette partie plus accessible est la bienvenue.

Pour commencer : la forge

La forge en informatique, et en particulier dans le monde du logiciel libre, est une plateforme web de travail collaboratif destinée à développer et partager des applications informatiques. Pour Bénévalibre, tout se passe sur forge.cliss21.org/cliss21/benevalibre. Il vous faudra vous y créer un compte si vous souhaitez :

  • Ouvrir un ticket : pour reporter un problème, suggérer une amélioration ou une nouvelle fonctionnalité. Merci de vous assurez qu’aucun ticket existant n’en parle déjà pour éviter les doublons. Si c’est le cas, vous pouvez toujours laisser un commentaire pour donner votre avis.

  • Contribuer à la documentation : après avoir sélectionné la page, vous avez la possibilité d’éditer directement le fichier correspondant et proposer vos modifications. Cette partie est encore en cours d’amélioration pour la rendre plus accessible.

  • Proposer une demande d’ajout : pour corriger un bug, améliorer une fonctionnalité ou en ajouter une. Hormis pour les corrections de bug, une demande d’ajout devrait toujours se référer à un ticket. Ils sont à la base des discussions au sein du comité de pilotage, qui est l’organe décideur pour le développement du logiciel.

Pour aller plus loin : le code

Bénévalibre est une application web écrite en Python grâce au framework Django. Elle repose sur quelques extensions pour éviter de réinventer la roue, mais se veut de rester assez simple dans sa conception et ses dépendances.

Côté interface, le framework Tailwind CSS est utilisé afin d’éviter autant que possible l’écriture de code CSS. Le but étant de mettre en forme les éléments d’interface au plus près de leur code HTML, c’est-à-dire dans les gabarits Django.

Le code est structuré ainsi :

  • docs/ : les sources de la documentation
  • assets/ : le code JavaScript et CSS non compressé, les images, icônes et autres éléments graphiques utilisés dans l’interface
  • benevalibre/ : le projet Django et ses applications (benevalibre, benevalibre.accounts et benevalibre.associations)
  • benevalibre/settings/ : les réglages du projet Django pour les différents environnements
  • benevalibre/templates/ : les gabarits de toutes les applications Django
  • tests/ : les tests de l’application

Mise en place de l’environnement

Pré-requis

  • Git
  • make
  • Node.js et npm
  • Python 3.10 ou plus récent
  • pip pour Python 3
  • python-venv

Sur un poste sous Debian, cela correspond aux paquets suivant :

  • git
  • make
  • npm
  • python3
  • python3-pip
  • python3-venv

Récupération du code

Une fois les dépendances satisfaites, le dépôt Git peut être cloné :

$ git clone https://forge.cliss21.org/cliss21/benevalibre
$ cd benevalibre/

Compilation des fichiers statiques

Les fichiers statiques (CSS, JavaScript, images et polices) sont générés et compressés grâce à Rsbuild dans le dossier benevalibre/static. Dans un environnement de développement, ils restent en mémoire et seront rechargés en cas de modification.

Commençons par installer les dépendances :

$ npm install

Les fichiers statiques n’étant pas contenus dans le dépôt Git, nous allons les compiler pour la suite :

$ npm run build

Installation de l’application

En ce qui concerne le code Python, nous allons travailler avec un environnement virtuel où nous y installerons les dépendances requises. Commençons par le créer et l’activer :

$ python3 -m venv venv
$ source env/bin/activate

Vous verrez désormais (venv) préfixer l’invite de commande. Cet environnement virtuel sera à activer à chaque fois que vous ouvrez un terminal pour travailler sur le code ou votre instance de développement.

Nous pouvons désormais installer les dépendances de l’application, ainsi que celles requises pour le développement :

(venv)$ python -m pip install -Ue . --group dev

Par défaut, une base SQLite sera utilisée avec d’autres paramètres adaptés pour un environnement local de développement. Vous pouvez néanmoins adapter cette configuration par défaut en créant un fichier config.env dans ce dossier, en partant du fichier d’exemple :

(venv)$ cp config.env.example config.env

La base de données doit maintenant être initialisée pour continuer, grâce au script manage.py qui fournit les commandes Django du projet :

(venv)$ ./manage.py migrate

Vous pourriez avoir besoin d’un compte administrateur, qu’on crée avec :

(venv)$ ./manage.py createsuperuser

Lancement du serveur local

Une fois que l’application est initialisée, nous pouvons lancer un serveur local de développement :

(venv)$ ./manage.py runserver

Si vous êtes amené⋅es à travailler sur les fichiers statiques, vous pouvez en parallèle lancer un autre serveur qui se chargera de les servir et les recompiler à chaque modification :

$ npm run dev

Avant de proposer une demande d’ajout

Vérifier les tests et la couverture

Les tests de l’application ne doivent en aucun échouer. De plus, lorsque du code est ajouté, celui-ci doit être couvert par un ou plusieurs tests afin d’assurer sa pérennité. Pour lancer les tests et avoir un aperçu du code qui n’est pas couvert :

$ make test

Lorsque vous travaillez sur de nouveaux tests, vous pouvez utiliser le marqueur wip (qu’on utilise avec @pytest.mark.wip) pour ne lancer que ces derniers :

$ make test-wip

Enfin, il est aussi possible de ne lancer que les tests qui ont échoué à la dernière exécution :

$ make test-failed

Pour plus de détails sur l’écriture des tests, vous pouvez commencer par lire les tests existants, mais aussi consulter la documentation de pytest. En général, seules les vues sont testées avec leurs différents scénarios, ce qui est suffisant pour couvrir la majorité du code.

Vérifier le formatage

En cas de modification du code Python, veuillez vous assurer du bon formatage avec :

$ make lint

Si des erreurs sont reportées, vous pouvez tenter de les corriger automatiquement :

$ make format

Enfin, le formatage du code CSS et JavaScript, ainsi que l’ordre des classes CSS dans les gabarits sont aussi à vérifier avec :

$ npm run lint

Si des erreurs sont reportées, vous pouvez tenter de les corriger automatiquement :

$ npm run format