Contribute code
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 git@github.com:osrd-project/osrd
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.
- Install
docker
. 13 - Follow OSRD’s README.
Share your changes
The source code of OSRD is available under the LGPLv3 license. By contributing to the codebase, you consent to the distribution of your changes under the project’s license.
LGPLv3 forbids modifying source code without sharing the changes under the same license: use other people’s work, and share yours!
This constraint does not propagate through APIs: You can use OSRD as a library, framework or API server to interface with proprietary software. Please suggest changes if you need new interfaces.
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.
If you are not used to Git, follow this tutorial
Create a branch
If you intend to contribute regularly, you can request access to the main repository. Otherwise, create a fork.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.Keep your branch up-to-date
git switch <your_branch> git fetch git rebase origin/dev
Open a pull request
Once your changes are ready, you have to request integration with thedev
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 tagsArea:<affected_area>
to show which part of the application have been impacted. It can be done through the web interface.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.
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