Tout d'abord, merci de souhaiter contribuer à Hesperides !
Il y a plein de façons d'aider le projet :
- tout d'abord, testez-le et dites-nous ce que vous en pensez !
- signalez-nous d'éventuels bugs que vous rencontrez
- suggérerez de nouvelles fonctionnalités ou des améliorations
- contribuez au code en corrigeant des bugs ou en ajoutant des fonctionnalités via des pull requests
Pour tout ça, le meilleure manière d'entrer en contact avec nous est via le système d'issues de GitHub, même simplement si vous avez des questions.
Elle est située dans le dossier tech_docs/ et détaille la structure du code ainsi que les conventions employées pour le CSS et les tests par exemple.
Pour les nouveaux venus, nous maintenons une liste de tâches faciles, incluant des corrections de bugs ou des émaliorations simples, pour vous permettre de débuter doucement avec le code.
Globalement voici comment procéder pour contribuer au code :
- Assurez-vous qu'il existe une issue détaillant la modification que vous voulez effectuer, bug ou fonctionnalité. Idéalement, indiquez dans cette issue que vous commencez à travailler dessus.
- Créez un fork de ce repo et installez votre environnement de développement.
- Codez !
- Poussez vos modifications sous forme de commit sur votre fork.
Idéalement, sur une branche dédiée et pas sur
masterpour vous permettre de travailler sur plusieurs tâches en parallèle. - Créer une pull request, et assurez-vous que Travis CI la valide. Mentionnez-le ensuite dans l'issue correspondante, et demandez une revue de code.
- Il est très probable qu'on vous suggère de faire quelques modifications : ajoutez simplement des commits sur la branche de votre fork et ils seront automatiquement inclus dans la pull request.
Lorsque vous aurez adressés tous les retours faits lors de la revue de code, un mainteneur du projet fusionnera votre contribution au code, en squashant vos commits.
Et voilà !
Vous aurez besoin d'une version récente de NodeJS et de npm.
De plus, nous utilisons Docker pour packager et déployer l'application. Vous en aurez besoin pour lancer le backend :
docker run --rm -p 8080:8080 -e API_ENDPOINT=... -e SPRING_PROFILES_ACTIVE=noldap,fake_mongo hesperides/hesperides
Afin d'effectuer certaines validations automatisées à chaque commit,
ce projet emploie des hooks git de pre-commit, via l'outil Python du même nom.
Les hooks configurés sont listés dans le fichier de configuration .pre-commit-config.yaml, et sont exécutés via Travis CI. Aucune PR ne sera mergée si ces hooks remontent des erreurs.
Dans la mesure du possible, installez ces hooks sur votre poste de développement. Si vous ne pouvez pas ou ne voulez pas prendre le temps de le faire, vous devrez vous baser sur les logs de Travis CI pour débugger d'eventuelles erreurs qu'ils détecteraient.
Pour les installer sur votre poste de développement, vous aurez besoin de Python,
et du paquet pre-commit qui peut être installé avec pip.
Pour configurer git afin qu'il exécute les hooks à chaque commit, lancez la commande suivante :
pre-commit install
Si besoin, vous pouvez lancer manuellement les hooks :
pre-commit run $hook_name # exécute un unique hook sur tous les fichiers modifiés
pre-commit run --files $file1 $file2 # exécute tous les hooks sur les fichiers spécifiés
pre-commit run --all-files # exécute tous les hooks sur tous les fichiers
Travis CI est configuré via le fichier .travis.yml pour exécuter les validations suivantes sur chaque pull request:
- analyse statique du code avec
eslint - exécutions de tous les hooks de
pre-commit - tests unitaires avec Karma
- tests end to end avec Protractor
Chaque pull request doit être relue par au moins un mainteneur du projet, et obtenir son approbation.
Les revues de code doivent suivre ces principes :
Pour visualiser la documentation sur votre machine :
npm run serve-doc