"Mails par Archifiltre" est un projet open-source auquel vous pouvez contribuer. Vous retrouverez ci-après les différentes règles et nomenclatures suivies dans ce dépôt.
- Git
- Produit
- Intégration continue et tests
- Déploiement continu + sortie de version
- Code et documentation
Le projet respecte une version allégée de "GitFlow".
- 🧑💻 La branche de développement est
dev- Cette branche est définie comme par défaut dans github
- Cette branche est protégée contre les commits venants d'utilisateurs non administrateurs
- 🏷️ La branche de production en cours est
main- Cette branche est protégée contre les commits venants d'utilisateurs non administrateurs
- ✨ Les branches de fonctionnalités doivent commencer par le préfixe
feature/oufeat/- Elles doivent partir de la branche
dev - Elles doivent être fusionnées dans la branche
dev
- Elles doivent partir de la branche
- 🐛 Les branches de correction de bugs doivent commencer par le préfixe
hotfix/oufix/- Quand un bug est détecté dans
dev- Elles doivent partir de la branche
dev - Elle doivent être fusionnée uniquement dans la branche
dev
- Elles doivent partir de la branche
- Quand un bug est détecté dans
main- Elles doivent partir de la branche
main - Elle doivent aussi avoir leurs commits (liés au bug) de picoré (🍒 "cherry-pick") vers la branche
dev- Un rebasage ("rebase") est déconseillé car picorer a l'avantage de conserver l'historique des commits sur la branche d'arrivée
- Elles doivent partir de la branche
- Quand un bug est détecté dans
- 👷 Les branches liées à l'intégration continue doivent commencer par le préfixe
ci/ouci-*/ - Les autres préfixes seront interprétés de manière standard (par rapport à l'exécution de la CI)
- Les autres noms de branches (sans préfixe) ne sont pas gérés
- Les multiples préfixes ne considérerons que le premier préfixe vis-à-vis des règles précédentes (ex:
feature/icicle/refacto=> ok feature ;icicle/feature/refacto=> ko)- Exception faite pour les branches
*/e2e/*(ex:feature/e2e/icicle,hotfix/e2e/bug-chargement-empreinte) qui adoptent cette nomenclature afin de déclencher les tests e2e en plus dans la CI
- Exception faite pour les branches
- 🤖 Les branches préfixées
renovate/sont réservées et ne doivent pas être utilisées
Représentation imagée :
La convention de commit adoptée par le projet est Conventional Commits MAIS cette convention n'est imposée que sur les branches principales dev et main.
En effet, les pull requests étant "squash", seul importe le commit de merge en fin de pull request.
Gitm😍 ji peut donc par exemple être utilisé à l'intérieur des branches si besoin.
Pour chaque fonctionnalité apportée ou bug corrigé, une pull request doit être faite.
Il faut obligatoirement lier une pull request à un ticket, sans ça, elle n'a aucun intérêt.
Vous pouvez vous aider du template prévu à cet effet. Il est important de bien respecter la convention Semantic Pull Request pour le titre des pull requests.
Comme dit plus haut, le format des commits sera ignoré au profit d'un squash de merge à la cloture de la pull request.
Les fonctionnalités suivent le processus de développement suivant :
- Une idée arrive dans le tableau des idées (accès interne)
- Cette idée est évaluée, travaillée, puis transformée en ticket pour le backlog global (accès interne) avec le label "archifiltre-mails"
- Ce ticket est une nouvelle fois travaillé pour être soit transformé en EPIC soit rattaché à une EPIC existante
- Si il devient une EPIC, il acquiert le label "EPIC" et reste dans le même tableau
- Si il est rattaché à une EPIC, il est raffiné puis transféré vers le tableau de sprint de
Mails(accès public)
Un ticket est toujours estimé avec une valeur business et une complexité, mesurés avec la technique du T-shirt sizing (S, M, L, XL).
Un ticket est autant que possible accompagné de critères d'acceptance définis entre la qualité et la définition du besoin. Ces critères sont la représentation des tests d'intégration et/ou E2E qui seront créés pour valider la fonctionnalité associée.
Un ticket est considéré comme terminé (DoD) lorsque les conditions suivantes sont remplies :
- Les critères d'acceptances ont été respectés
- Tous les tests d'intégration passent au vert ✅
- Si la valeur business est XL (ou L si besoin), tous les tests E2E passent au vert ✅
- (voir E2E)
- En respect de l'engagement de sécurité, 1 review obligatoire à partir de la complexité M
Trois types de tests sont mis en place dans l'application : composants, intégration, et end-to-end (E2E).
Les tests de composants sont comme des tests unitaires, à écrire autant que possible pour limiter au maximum les potentiels régressions graphiques.
Les tests d'intégration peuvent être liés aux critères d'acceptances (ou à une partie) afin de tester une fonctionnalité précise dans son ensemble.
Les tests E2E sont fortement et souvent liés aux critères d'acceptances en plus d'être "scénarisés" pour être ensuite développés et exécutés pendant les phases de recette.
Régulièrement, des bots de contrôle passent sur le code pour garantir le maintiens des dépendances directes à jour, ainsi que l'application de leurs derniers patch de sécurité (Dependabot 🤖).
Les tests se situent dans le dossier ./tests/ et peuvent être exécutés avec la commande yarn test.
Automatiquement, les pull requests dont les branches sont à destination de dev et main sont contrôlées sur leur qualité via CodeQL ainsi que sur notre CI interne.
Notre CI contrôlera de son côté l'uniformité du code (lint), compilera le code pour vérifier son intégrité, et lancera les tests "classiques" (composants et intégration).
Les tests E2E se situent dans le dossier ./tests/e2e/ et peuvent être exécutés avec la commande yarn test:e2e.
Attention toutefois à bien installer les prérequis en amont. (cf README).
Les tests e2e s'exécuteront automatiquement dans la CI suivant l'une de ces conditions :
- toutes les nuits, avant un jour de semaine travaillé, à 1h du matin sur la branche
dev - à chaque pull request en direction de la branche
main - à chaque push sur les branches
ci-e2e/*ou*/e2e/*
Les tests e2e seront automatiquement lancés sur les trois systèmes d'exploitation ciblés, à savoir Linux Ubuntu, Windows, et MacOS.
Il est donc important dans le cas de code spécifique à l'un des OS de bien définir une non exécution des tests pour les autres.
Comme l'ensemble des produits Archifiltre, Mails est déployé en continue en fonction des phases de développement.
Chaque nuit à 1h du matin, une version de développement next sort si du code a été poussé dans la journée sur la branche dev. Cette version est itérative, et compatible avec le système de mise à jour automatique.
Consultez la page de release pour plus d'informations.
Avant de contribuer au projet, il est fortement conseillé d'installer et désinstaller les extensions recommandées de VSCode. (listées ici). Dans la majeure partie des cas, ces extensions ont été configurées pour offrir une expérience développeur adéquat.
Lors des développements, il est obligatoire de respecter les conventions de code dictées par l'outils de lint (lançable avec la commande yarn lint).
Enfin, dans un esprit d'amélioration continue, pour chaque contribution, il est essentiel d'apporter au maximum de la documentation afin de donner du contexte sous la forme de commentaires sensés dans le code, et si besoin, de faire évoluer la documentation existante (par exemple lors de l'ajout de nouveaux modules et services dans dans la page associée le cas échéant).