This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Contribute to OSRD

Learn about the how we work, and how you can work with us

First off, thanks for taking the time to contribute!

The following chapters are a set of guidelines for contributing to OSRD1. If you have already contributed to open source projects before, you probably won’t be surprised. If you have not, it will probably help a lot!


Chatting with other contributors is a great way to speed things up:


Just like with any project, changes rely on past work. Before making changes, it is best to learn about what’s already there:

  • read technical documentation
  • read the existing source code related to your project
  • chat with developers who last worked on areas you are interested in

  1. These guidelines are mostly not strict rules, it’s probably fine to do things slightly differently. ↩︎

1 - Batch dependency updates

For editoast

We use dependabot on the project to signal when dependencies are outdated. We do not use dependabot to automatically update dependencies, as we want to merge all updates at once and review the changes.

Here is the process to update dependencies:

  1. Change the versions.
    • If you’re using VSCode you can install the serayuzgur.crates extension and run the “update all dependencies” command.
      Make sure that the new version chosen is stable, and that loose constraints are not overwritten in your commit.
    • If you’re not, you can go check the versions used by dependabot in its PRs and update the versions manually.
  2. Run cargo update to update the Cargo.lock file (even sub-dependencies).
  3. Check that all dependabot editoast PRs are included in your update.
  4. Adapt the code to the new versions, if needed.
  5. Create a PR with your changes, and link all dependabot PRs in the description.

2 - Report issues

Report a bug or suggest an enhancement

Please report anything you deem significant!

Our bug tracking platform is github, so you have to register to report bugs.

Follow this link and pick whatever template fits the best.


  • Bug must have a correct description and the bug’s issue template must be filled carefully.
  • Bug must be tagged with (for team members):
    • kind:bug
    • one or several area:<affected_area> if possible, if the affected area is not known leave it blank it will be added later by another team member.
    • one severity:<bug_severity> if possible, if severity is not known leave it blank it will be added later by another team member.
      • severity:minor: User can still use the feature.
      • severity:major: User sometimes can’t use the feature.
      • severity:critical: User can’t use the feature.
  • OSRD team members can change issues’ tags (severity, area, kind, …). You may leave a comment to explain changes.
  • If you are working on a bug or plan to work on a bug, assign yourself to the bug.
  • PRs solving bugs should add a regression tests to ensure that bug will not be back in the future.

3 - Contribute code

Integrate changes into OSRD

Set things up

Get the source code

  • Install git.1
  • Open a terminal2 in the folder where the source code of OSRD will be located
  • Run git clone

Launch the application

Thanks to docker, one can easily compile, configure, and run all services after making a change. One can also start only a subset of the services.

Share your changes

This chapter is about the process of integrating changes into the common code base. If you need help at any stage, open an issue or message us.

  1. If you are not used to Git, follow this tutorial

  2. Create a branch
    If you intend to contribute regularly, you can request access to the main repository. Otherwise, create a fork.

  3. Add changes to your branch
    Before you start working, try to split your work into macroscopic steps. At the end of each stop, save your changes into a commit. Try to make commits of logical and atomic units. Try to follow style conventions.

  4. Keep your branch up-to-date

    git switch <your_branch>
    git fetch
    git rebase origin/dev
  5. Open a pull request
    Once your changes are ready, you have to request integration with the dev branch. If possible, make PR of logical and atomic units too (avoid mixing refactoring, new features and bug fix at the same time). Add a description to PRs to explain what they do and why. Help the reviewer by following advice given in mtlynch article. Add tags Area:<affected_area> to show which part of the application have been impacted. It can be done through the web interface.

  6. Take feedback into account
    Once your pull request is open, other contributors can review your changes:

    • Any user can review your changes
    • Your code has to be approved by a contributor familiar with the code
    • All users are expected to take comments into account.
    • Comments tend to be written in an open and direct manner. The intent is to efficiently collaborate towards a solution we all agree on.
    • Once all discussions are resolved, a maintainer integrates the change.

    As a reviewer try to follow advice given in mtlynch article.

  7. If you believe somebody forgot to review / merge your change, please speak out, multiple times if needs be.

Git commit style

The overall format for git commits is as follows:

component: imperative description of the change

Detailed description of the change and what motivates it,
if it is not entirely obvious from the title.
  • the commit message, just like the code, must be in english
  • all lowercase
  • there can be multiple components separated by : in case of hierarchical relationships, with , otherwise
  • the body of the commit should probably contain a detailed description of the change

  1. Under Linux, use your distribution’s package manager, such as apt-get ↩︎ ↩︎

  2. Under Windows, open Git Bash ↩︎

  3. Under Windows/WSL, Docker Desktop is recommended ↩︎

4 - Style guide

Coding style guide and best practices

OSRD application is split in multiple services written in several languages. We try to follow general code best practices and follow specificity for each languages when required.

General rules

  • Explain what you’re doing and why.
  • Document new code with doc comments.
  • Include clear, simple tests.
  • Break work into digestible chunks.
  • Take the time to pick good names.
  • Avoid non well-known abbreviations.
  • Control and consistency over 3rd party code reuse: Only add a dependency if it is absolutely necessary.
  • Every dependency we add decreases our autonomy and consistency.
  • Don’t reinvent every wheel: As a counter to the previous point, don’t reinvent everything at all costs.
  • If there is a dependency in the ecosystem that is the “de-facto” standard, we should heavily consider using it.
  • More code general recommendations in main repository
  • Ask for any help that you need!

4.1 - Back-end

Coding style guide and best practices for back-end


Python code is used for some packages and integration testing.


  • As a reference for our API development we are using the Rust API guidelines. Generally, these should be followed.
  • Prefer granular imports over glob imports like diesel::*.
  • Tests are written with the built-in testing framework.
  • Use the documentation example to know how to phrase and format your documentation.
  • Use consistent comment style:
    • /// doc comments belong above #[derive(Trait)] invocations.
    • // comments should generally go above the line in question, rather than in-line.
    • Start comments with capital letters. End them with a period if they are sentence-like.
  • Use comments to organize long and complex stretches of code that can’t sensibly be refactored into separate functions.
  • Code is linted with clippy.
  • Code is formatted with fmt.


4.2 - Front-end

Coding style guide and best practices for front-end

Nous utilisons ReactJS et tous les fichiers doivent être écrits en Typescript.

Le code est linté avec eslint, et formaté avec prettier.


Diagramme de l&rsquo;Infrastructure

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 components qui héberge tous les composants
  • un répertoire styles optionnel par module pour le style des composants en scss
  • un répertoire assets optionnel par module (qui contient les assets, de jeux de données par défaut par ex, spécifiques au module)
  • un fichier reducers optionnel par module
  • un fichier types optionnel par module
  • un fichier consts optionnel par module

Un répertoire assets (qui contient les images et autre fichiers).

Enfin, un répertoire common qui propose :

  • un répertoire utils pour les fonctions utilitaires communes à l’ensemble du projet
  • un fichier types pour les types communs à l’ensemble du projet
  • un fichier consts pour les constantes communes à l’ensemble du projet

Principes d’implémentation

Routage & SLUG

Rédaction en cours

projects/{nom du projet}/studies/{nom de l'étude}/scenarios/{nom du scenario}

Styles & SCSS

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 scss au 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, 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.

Noms de classes, utilisation de 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 librairie classnames qui préconise l’usage suivant :

<div className="rollingStockSelector">
  <div className="rollingStockList">
    <div className="rollingStockCard w-100 my-2">
        className={cx('rollingStockImg', 'm-2', 'p-1', 'bg-white', {
          valid: isValid(),
          selected: rollingStockID === selectedRollingStockID,

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 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.


Rédaction en cours

Utiliser les endpoints générés à partir des fichiers openapi.yaml pour consommer le backend.

Lois et éléments importants

Aucun composant ne doit détenir la responsabilité de mise à jour de la donnée qu’il utilise

Seules les vues contiennent les sélecteurs du store, donnés ensuite en props aux composants du module lié à la vue.

Le SCSS n’est pas scopé

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.

Les liens des imports doivent être absolus au sein d’une application

Vous devez utiliser le chemin complet pour tous vos imports, même si le fichier à importer se trouve dans le même répertoire.

Les liens des imports doivent être relatifs au sein d’un module ou d’un composant

Au sein d’un module ou d’un composant, à l’instar d’une librairie, les liens d’imports doivent rester relatifs afin de permettre leur utilisation n’importe où.


import & export

We recommend using typed imports and exports.

When an import or export contains only types, indicate it with the type keyword.

export type { Direction, DirectionalTrackRange as TrackRange };
import type { typedEntries, ValueOf } from 'utils/types';

This allows to:

  • Improve the performance and analysis process of the compiler and the linter.
  • Make these declarations more readable; we can clearly see what we are importing.
  • Avoid dependency cycles:

dependency cyle

The error disappears with the type keyword

dependency cyle

  • Make final bundle lighter (all types disappear at compilation)

4.3 - Tests

Recommandations for testing purpose


  • Integration tests are written with pytest in the /tests folder.
  • Each route described in the openapi.yaml files must have an integration test.
  • The test must check both the format and content of valid and invalid responses.


The functional writing of the tests is carried out with the Product Owners, and the developers choose a technical implementation that precisely meets the needs expressed and fits in with the recommendations presented here.

We use Playwright to write end-to-end tests, and vitest to write unit tests.

The browsers tested are currently Firefox and Chromium.

Basic principles

  • Tests must be short (1min max) and go straight to the point.
  • Arbitrary timeouts are outlawed; a test must systematically wait for a specific event. It is possible to use polling (retry an action - a click for example - after a certain time) proposed in the Playwright’s API.
  • All tests must be parallelizable.
  • Tests must not point to or wait for text elements from the translation, prefer the DOM tree structure or place specific id.
  • We’re not testing the data, but the application and its functionality. Data-specific tests should be developed in parallel.


The data tested must be public data. The data required (infrastructure and rolling stock) for the tests are offered in the application’s json files, injected at the start of each test and deleted at the end, regardless of its result or how it is stopped, including with CTRL+C.

This is done by API calls in typescript before launching the actual test.

The data tested is the same, both locally and via continuous integration.

Atomicity of a test

Each test must be atomic: it is self-sufficient and cannot be divided.

A test will target a single feature or component, provided it is not too large. A test will not test an entire module or application; it will necessarily be a set of tests, in order to preserve test atomicity.

If a test needs elements to be created or added, these operations must be carried out by API calls in typescript upstream of the test, as is done for adding data. These elements must be deleted at the end of the test, regardless of the result or how it is stopped, including by CTRL+C.

This allows tests to be parallelized.

However, in certain cases where it is relevant, a test may contain several clearly explained and justified test subdivisions (several test() in a single describe()).

Example of a test

The requirement: “We want to test the addition of a train to a timetable”.

  1. add the test infrastructure and rolling stock to the database by API calls.
  2. create project, study and scenario with choice of test infrastructure by API calls.
  3. start the test, clicking on “add one or more trains” until the presence of the trains in the timetable is verified
  4. the test passes, fails or is stopped, the project, study and scenario are deleted, along with the test rolling stock and infrastructure by API calls.

NB: the test will not test all the possibilities offered by the addition of trains; this should be a specific test which would test the response of the interface for all scenarios without adding trains.

5 - Review code

How to give useful feedback