Contribute code

Integrate changes into OSRD

Set things up

Getting the source code

  • Install git.1
  • Open a terminal2 in the folder where the source code of OSRD will be located
  • Run git clone git@github.com:DGEXSolutions/osrd

Launch the application with docker-compose

For a long time, making changes to a component of a multi-service application involved compiling, configuring and running all services manually.

Nowadays, it can be done using docker compose. You can even start only a subset of the services.

  • Install docker and docker compose. 1
  • Run docker compose up --build

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 ↩︎