Version imprimable multipages. Cliquer ici pour imprimer.
Ce chapitre décrit le processus aboutissant à l’intégration de code au sein du projet. Si vous avez besoin d’aide, ouvrez une issue ou envoyez un message instantané.
L’application OSRD est divisée en plusieurs services écrits dans plusieurs langues. Nous essayons de suivre les bonnes pratiques générales en matière de code et de respecter les spécificités de chaque langage lorsque cela est nécessaire.
README.md de chaque composant).Consulter les conventions pour le back-end ‣
Consulter les conventions pour le front-end ‣
Le code Python est utilisé pour certains paquets et pour les tests d’intégration.
diesel::*./// les commentaires de la documentation sont au-dessus des invocations #[derive(Trait)].// doivent généralement être placés au-dessus de la ligne en question, plutôt qu’en ligne.Nous utilisons ReactJS et tous les fichiers doivent être écrits en Typescript.
Le code est linté avec eslint, et formaté avec prettier.
Les applications (osrd eex, osrd stdcm, éditeur infra, éditeur matériel) proposent des vues (gestion des projets, gestions des études, etc.) liées à des modules (projet, étude, etc.) qui contiennent les composants.
Ces vues sont constituées de composants et sous-composants tous issus des modules. En plus de contenir les fichiers de vues des applications, elles peuvent contenir un répertoire scripts qui propose des scripts liés à ces vues. Les vues déterminent la logique et l’accès au store.
Les modules sont des collections de composants rattachés à un objet (un scénario, un matériel roulant, un TrainSchedule). Ils contiennent :
Un répertoire assets (qui contient les images et autre fichiers).
Enfin, un répertoire common qui propose :
On utilise en général les conventions suivantes dans le code:
ATTENTION : en CSS/React, le scope d’une classe ne dépend pas de l’endroit où le fichier est importé mais est valide pour toute l’application. Si vous importez un fichier
scssau fin fond d’un composant (ce que nous déconseillons fortement par ailleurs), ses classes seront disponibles pour toute l’application et peuvent donc provoquer des effets de bord.
Il est donc très recommandé de pouvoir facilement suivre l’arborescence des applications, vues, modules et composants également au sein du code SCSS, et notamment imbriquer les noms de classes pour éviter les effets de bord.
Quelques conventions supplémentaires:
string et les opérations booléennes ou autres sont réalisées dans un objet qui retournera — ou pas — le nom de propriété comme nom de classe à utiliser dans le CSS.Le store permet de stocker des données qui seront accessibles à n’importe quel endroit de l’application. Il est découpé en slices, qui correspondent à nos applications.
Attention cependant à ce que notre store ne devienne pas un fourre-tout. L’ajout de nouvelles propriétés dans le store doit être justifié par le fait que la donnée en question est “haut-niveau” et devra être accessible depuis des endroits éloignés de la code base, et qu’une simple variable de state ou de contexte ne soit pas pertinent pour stocker cette information.
Pour plus de détails, nous vous invitons à consulter la documentation officielle.
Nous utilisons Redux ToolKit pour réaliser nos appels au backend.
RTK permet notamment de faire des appels à l’api et de mettre en cache les réponses. Pour plus de détails, nous vous invitons à consulter la documentation officielle.
Les endpoints et les types du backend sont générés directement à partir de l’open-api d’editoast et stockés dans generatedOsrdApi (avec la commande npm run generate-types). Ce fichier généré est ensuite enrichi par d’autres endpoints ou types dans osrdEditoastApi, qui peuvent être utilisés dans l’application.
A noter qu’il est possible de transformer des mutations en queries lors de la génération de generatedOsrdApi en modifiant le fichier openapi-editoast-config.
Lorsqu’un appel d’endpoint doit être skip parce qu’une variable n’est pas définie, on utilise skipToken de RTK pour éviter de devoir mettre des casts.
La traduction de l’application est effectuée sur Weblate.
Il est recommandé d’utiliser le chemin complet pour chaque import, sauf si votre fichier à importer est dans le même répertoire.
ESLint est configuré pour trier automatiquement les imports en 4 groupes, séparés par une ligne vide et chacun trié alphabétiquement :
Concernant l’import/export de types, ESLint et Typescript sont configurés de manière à ajouter automatiquement type devant un import de types, ce qui permet de:
type)
Si vous n’être pas un habitué de Git, suivez ce tutoriel
Créez une branche
Si vous comptez contribuer régulièrement, vous pouvez demander accès au dépôt principal. Sinon, créez un fork.
Ajoutez des changements sur votre branche
Essayez de découper votre travail en étapes macroscopiques, et sauvegardez vos changements dans un commit à la fin de chaque étape. Essayez de suivre les conventions du projet.
Conservez votre branche à jour
git switch <your_branch>
git fetch
git rebase origin/dev
Le format général des commits est le suivant :
composant1, composant2: description du changement à l'impératif
Description détaillée ou technique du contenu et de la motivation du
changement, si le titre n'est pas complètement évident.
: quand il y a une relation hiérarchique, ou des , sinon-, _ ou .# est interdit)Idéalement :
A éviter absolument:
component: update ./some/file.ext : préciser la mise à jour en question plutôt que le fichier,
les fichiers sont des éléments techniques bienvenus dans le corps du commitcomponent: fix #42 : préciser le problème corrigé, les liens (vers l’issue, etc.) sont
encouragés dans le corps du commitwip : décrire le travail (et le finir)Bienvenus pour faciliter la relecture, mais ne pas merger:
fixup! previous commit : un autosquash devra être lancé avant le mergeRevert "previous commit of the same PR" : les deux commits devront être retirés avant mergeTous les projets d’OSRD utilisent le DCO (certificat du développeur d’origine) pour des raisons légales. Le DCO permet de confirmer que vous avez les droits sur le code que vous contribuez. Pour en savoir plus sur l’histoire et l’objectif du DCO, vous pouvez lire The Developer Certificate of Origin de Roscoe A. Bartlett.
Pour se conformer au DCO, tous les commits doivent inclure une ligne Signed-off-by.
Pour signer un commit, il suffit d’ajouter l’option -s à votre commande git commit, comme ceci :
git commit -s -m "Your commit message"
Cela s’applique également lors de l’utilisation de la commande git revert.
Allez dans Fichiers -> Préférences -> Paramètres, puis recherchez et
activez le paramètre Always Sign Off.
Ensuite, lorsque vous ferez un commit via l’interface de VS Code, ils seront automatiquement signés.
L’auteur d’une pull request (PR) est responsable de son « cycle de vie ». Il se charge de contacter les différents acteurs, de suivre la revue de code, répondre aux commentaires et corriger le code suite à la revue de code (vous pouvez également consulter la page dédiée à la revue de code).
Ouvrez une pull request
Une fois que vos changements sont prêts, il est temps de proposer de les intégrer à la branche dev.
Cela se fait dans l’interface web de Github.
Si possible :
area:<affected_area> pour montrer quelle partie de l’application a été impactée. Cela peut être fait via l’interface web.Prenez en compte les retours
Une fois que votre PR est ouverte, d’autres contributeurs doivent donner leur avis sur votre proposition :
Dans l’idéal, évitez les PR conséquentes et découpez le travail en plusieurs PR1 :
- facilite la relecture et peut aussi l’accélérer (plus facile de trouver 1 heure pour faire une relecture qu’une demi-journée),
- permet une approche plus agile avec des retours sur les premières itérations avant d’enchaîner sur la suite,
- garde un historique git plus simple à explorer (notamment lors d’un
git bisectà la recherche d’une regression par exemple).En cas d’impossibilité à éviter une PR conséquente, ne pas hésiter à solliciter plusieurs relecteurs qui pourront s’organiser, voire de faire la relecture ensemble, relecteurs et auteur.
Sur les PR conséquentes et vouées à évoluer dans le temps, conserver les corrections suite à la relecture dans des commits séparés facilite le travail de relecture. En cas de
rebaseet de relectures multiples par la même personne ils sont le moyen d’économiser une nouvelle relecture complète (demandez de l’aide au besoin) :
- Ajoutez des commits de fixup, amend, squash ou reword à l’aide de la documentation dédiée à git commit.
- Fusionnez automatiquement les corrections dans les commits originaux de votre PR et vérifier le résultat , à l’aide de
git rebase -i --autosquash origin/dev(juste avant le merge et une fois les relectures terminées).- Poussez vos changements avec
git push --force-with-leasecar vous ne poussez pas seulement de nouveaux commits, mais bien un changement des commits existants.
Une revue de code est un processus itératif. Pour la fluidité d’une review, il est impératif de configurer correctement ses notifications github.
Il est conseillé de configurer les dépôts OSRD en “Participating and @mentions”. Cela permet d’être notifié d’activités uniquement sur les issues et PR auxquelles vous participez.
sequenceDiagram
actor A as Auteur PR
actor R as Reviewer/mainteneur
A->>R: Demande une review en notifiant spécifiquement quelques personnes
R->>A: Répond à la demande par oui ou non
loop Boucle entre auteur et reviewer
R-->>A: Commente, demande des changements
A-->>R: Répond à chaque commentaire/demande de changement
A-->>R: Corrige le code si nécessaire dans des « fixups » dédiés
R-->>A: Vérifie, teste, et commente à nouveau le code
R-->>A: Résout les conversations/demandes de changement le cas échéant
end
A->>R: Rebase si nécessaire
R->>A: Vérifie l'historique des commits
R->>A: Approuve la PR
Note right of A: Ajoute à la merge queueLes mainteneurs sont automatiquement notifiés par le système de
CODEOWNERS. L’auteur d’une PR est responsable de faire avancer sa PR dans le processus de review (quitte à notifier manuellement un mainteneur).
Continuer enfin vers les tests ‣
si vous n’êtes pas convaincus, cherchez “Stacked Diff” sur le web pour plus de détails sur le sujet, comme Stacked Diffs vs. Trunk Based Development (en) ↩︎
/tests.openapi.yaml doit avoir un test d’intégration.L’écriture fonctionnelle des tests est réalisée avec les Product Owners, et les développeurs choisissent une implémentation technique qui répond précisément aux besoins exprimés et qui s’intègre dans les recommandations présentes ici.
Nous utilisons Playwright pour écrire les tests bout en bout, et vitest pour écrire les tests unitaires.
Les navigateurs testés sont pour l’instant Firefox et Chromium.
id spécifiques.Les données testées doivent impérativement être des données publiques.
Les données nécessaires (infrastructure et matériel) aux tests sont proposées dans des fichiers json de l’application, injectées au début de chaque test et effacées à la fin peu importe son résultat ou la manière d’être stoppé, y compris par CTRL+C.
Cela se fait par des appels API en typescript avant de lancer le test à proprement parler.
Les données testées sont les mêmes en local ou via l’intégration continue.
Les tests e2e sont implémentés de manière itérative, et livrés en même temps que les développements. À noter que:
Chaque test doit être atomique : il se suffit à lui-même et ne peut pas être divisé.
Un test va cibler une fonctionnalité ou un composant, si ce dernier n’est pas trop gros. Un test ne testera pas tout un module ou tout une application, ce sera forcément un ensemble de tests afin de préserver l’atomicité des tests.
Si un test a besoin que des éléments soient créés ou ajoutés, ces opérations doivent être opérées par des appels API en typescript en amont du test, à l’instar de ce qui est fait pour l’ajout de données. Ces éléments doivent être supprimés à l’issue du test, peu importe son résultat ou la manière d’être stoppé, y compris par CTRL+C.
Cela permettra notamment la parallélisation des tests.
Un test peut cependant, dans certains cas de figure où cela est pertinent, contenir plusieurs sous-divisions de test, clairement explicitées, et justifiées (plusieurs test() dans un seul describe()).
Le besoin : « nous voulons tester l’ajout d’un train dans une grille horaire ».
NB : le test ne va pas tester toutes les possibilités offertes par l’ajout de trains, cela relève d’un test spécifique qui testerait la réponse de l’interface pour tous les cas de figure sans ajouter de trains.