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 :
Rédaction en cours
projects/{nom du projet}/studies/{nom de l'étude}/scenarios/{nom du scenario}
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. Vous pouvez utiliser les CSS modules pour éviter les conflits.
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, le compilateur se chargera de fabriquer la hiérarchie nécessaire.
Si par exemple nous avons un composant rollingStockSelector qui propose une liste de matériel rollingStockList représentés par des cartes rollingStockCard contenant une image représentant le matériel roulant rollingStockImg nous devrions avoir la structure SCSS suivante :
.rollinStockSelector {
.rollingStockList {
.rollingStockCard {
.rollingStockImg {
width: 5rem;
height: auto;
}
}
}
}
Ainsi, on a la garantie que l’image contenue dans la carte de matériel roulant héritera bien des bonnes propriétés css .rollinStockSelector.rollingStockList.rollingStockCard.rollingStockImg.
Les CSS modules permettent de scoper les styles CSS à un composant spécifique, évitant ainsi les conflits de noms de classe globaux.
Vite prend en charge nativement les CSS modules. Assurez-vous que votre fichier CSS a l’extension .module.css. Par exemple, styles.module.css.
.module.scss :/* MyComponent.module.scss */
.container {
background-color: white;
}
.title {
font-size: 24px;
color: #333;
}
Vite transforme les classes en objets qui contiennent les classes hashées (exemple _container_h3d8bg) et les utilise au moment de la génération du bundle, rendant ainsi les classes uniques.
import React from "react";
import styles from "./MyComponent.module.scss";
export function MyComponent() {
return (
<div className={styles.container}>
<h1 className={styles["title"]}>Mon Titre</h1>
</div>
);
}
Pour plus d’information, vous pouvez regarder la documentation de vite.js
cx()Les classes sont ajoutées les unes à la suite des autres, normalement, dans la propriété className="".
Cependant, quand cela est nécessaire — tests pour l’utilisation d’une classe, concaténation, etc. — nous utilisons la bibliothèque classnames qui préconise l’usage suivant :
<div className="rollingStockSelector">
<div className="rollingStockList">
<div className="rollingStockCard w-100 my-2">
<img
className={cx("rollingStockImg", "m-2", "p-1", "bg-white", {
valid: isValid(),
selected: rollingStockID === selectedRollingStockID,
})}
/>
</div>
</div>
</div>
Les classes sont séparées chacune dans un 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.
Tout ce qui est selector est géré par la vue et passé en props aux composants et sous-composants.
Par conséquent les appels au store en lecture et en écriture doivent être passés un niveau de la vue, en irrigant par des props et states les composants proposées par la vue.
Utiliser les endpoints générés à partir des fichiers openapi.yaml pour consommer le backend.
Lorsque de la donnée est récupérée depuis le back, RTK va mettre cette donnée en cache dans le store. Si le même endpoint est appelé avec les même paramètres, RTK va réutiliser la donnée dans le cache plutôt que de rappeler le back.
Dans le store, vous verrez cette clé editoastApi qui contient la donnée en cache de tous les endpoints editoast :
Ici par exemple l’endpoint getProjects a été appelé.
RTK stocke le nom de l’endpoint, ainsi que les paramètres d’appel, pour former une clé unique nomDuEndpoint({ paramètres }). (ici getProjects({"ordering":"LastModifiedDesc","pageSize":1000})).
{
'getProjectsByProjectIdStudiesAndStudyId({"projectId":13,"studyId":16})': {
status :"fulfilled",
etc…
},
'getProjectsByProjectIdStudiesAndStudyId({"projectId":13,"studyId":14})': {
…
}
}
Dans ce deuxième exemple, le même endpoint a été appelé avec le même paramètre projectId, mais un paramètre studyId différent.
Les string utilisées comme clé dans le cache sont à peu de choses près l’objet paramètre passé à la moulinette JSON.stringify que transforme un object JS en string (donc sérialisé).
Normalement La sérialisation ne conserve pas l’ordre des clés des objets. Par exemple, JSON.stringify ne produira pas la même string avec ces deux objets: { a: 1, b: 2 } et { b: 2, a: 1 }.
RTK va optimiser la mise en cache en faisant en sorte que le résultat d’un appel avec {"projectId":13,"studyId":16} ou {"studyId":16, "projectId":13} soient stockées dans la même clé dans le cache.
Pour voir le fonctionnement en détail, voici le code de cette fonction de sérialisation :
const defaultSerializeQueryArgs: SerializeQueryArgs<any> = ({
endpointName,
queryArgs,
}) => {
let serialized = ''
const cached = cache?.get(queryArgs)
if (typeof cached === 'string') {
serialized = cached
} else {
const stringified = JSON.stringify(queryArgs, (key, value) =>
isPlainObject(value)
? Object.keys(value)
.sort() // les clés sont remises dans l’ordre ici
.reduce<any>((acc, key) => {
acc[key] = (value as any)[key]
return acc
}, {})
: value
)
if (isPlainObject(queryArgs)) {
cache?.set(queryArgs, stringified)
}
serialized = stringified
}
// Sort the object keys before stringifying, to prevent useQuery({ a: 1, b: 2 }) having a different cache key than useQuery({ b: 2, a: 1 })
return `${endpointName}(${serialized})`
}
Dans la terminologie de RTK query, Lorsqu’un composant react appelle un endpoint défini dans RTK Query, il souscrit à la donnée.
RTK compte le nombre de référence à la même paire (endpoint,{paramètres}). Lorsque deux composants souscrivent à la même donnée. Ils partagent la même clé dans le cache.
import { osrdEditoastApi } from "./api.ts";
function Component1() {
// component subscribes to the data
const { data } = osrdEditoastApi.useGetXQuery(1);
return <div>...</div>;
}
function Component2() {
// component subscribes to the data
const { data } = osrdEditoastApi.useGetXQuery(2);
return <div>...</div>;
}
function Component3() {
// component subscribes to the data
const { data } = osrdEditoastApi.useGetXQuery(3);
return <div>...</div>;
}
function Component4() {
// component subscribes to the *same* data as ComponentThree,
// as it has the same query parameters
const { data } = osrdEditoastApi.useGetXQuery(3);
return <div>...</div>;
}
Ici Component3 et Component4 ne vont générer qu’un seul appel vers le back. Ils souscrivent à la même donnée (même endpoint et même paramètre 3). Ils vont partager la même clé dans le cache.
Au total ici il y aura trois appels vers le back, avec les paramètres 1, 2, 3.
Tant qu’il existe au moins un composant react monté, qui appelle le hook osrdEditoastApi.endpoints.getProjectsByProjectId.useQuery par exemple, la donnée sera conservée dans le cache.
Dès que le dernier composant est démonté, la donnée est supprimée du cache au bout de 60 secondes (valeur par défaut).
La traduction de l’application est effectuée sur Transifex. La langue par défaut est le français. A noter que si l’on doit corriger une traduction, il est recommandé de passer par Transifex. En revanche, si on ajoute une nouvelle clé de traduction, celle-ci peut être ajoutée dans le code directement, dans toutes les langues disponibles.
Seules les vues contiennent les sélecteurs du store, donnés ensuite en props aux composants du module lié à la vue.
Un fichier .scss enfoui dans l’arborescence ne vous garantit pas que les classes contenues soient seulement accessibles à cet endroit, y compris par import react (formellement interdit au passage : vous devez utiliser l’import SCSS), toutes les classes déclarées sont accessibles partout.
Préférez un choix judicieux de nom de classe racine pour un module donné et utilisez l’arborescence possible dans le fichier SCSS.
ESLint est configuré pour trier automatiquement les imports en 4 groupes, chacun trié alphabétiquement :
Chacun de ces groupes est séparé par une ligne vide.
ESLint déclenchera un avertissement si ces recommandations ne sont pas respectées.
Vous devez utiliser le chemin complet pour tous vos imports.
Le chemin peut être relatif seulement si le fichier à importer est dans le même répertoire.
ESLint et Typescript sont configurés pour imposer l’import type pour un import de type.
Ceci permet de :
type devant l’import quand on ajoute un type avec l’autocomplétion dans un fichier.type devant l’import si vous ne l’avez pas fait.Lorsque qu’un import ou un export ne comporte que des types, il faut l’indiquer par le mot clé type.
export type { Direction, DirectionalTrackRange as TrackRange };
import type { typedEntries, ValueOf } from "utils/types";
Quand un import ne contient pas que des types, il sera agencé de cette manière, par ordre alphabétique.
import {
osrdEditoastApi,
type ScenarioCreateForm,
} from "common/api/osrdEditoastApi";
Cette pratique permet de :
L’erreur disparaît avec le mot clé 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épot 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’orgine) 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).
En cas de PR conséquente, ne pas hésiter à solliciter plusieurs reviewers qui pourront s’organiser, voire de faire la review ensemble, reviewers et auteur.
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 :
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éciquement 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 ou ferme la PR
Note left of R: Et fusionne si mainteneurLes 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).
/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.
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.