Thank you for your interest and for contributing to this project !
Before contributing, please, read and adhere to :
- the Code of Conduct to keep this community healthy, approachable and respectable;
- and the Developer's Certificate of Origin if you want to add code or documentation to this project.
In this guide you will get an overview of different contribution workflows :
- Bug reports
- Feature requests
- No-Code contributions
- Code contributions
- Pull Requests
Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
If you spot a bug in the code or in any other part of this project, you can create an issue.
But before you open a new issue, please search for older ones that cover the same issue. If you find one, please, avoid "me too" comments. You can add a +1 emoji reaction to the issue if you want to express interest in this.
When using the issue tracker, you will have an issue template for bugs. Don't worry if you can't answer every detail, just fill in what you can.
When possible, try to recreate the bug inside a docker container and give us your instructions to do it. Clear and easily reproducible instructions are your best gift for us <3.
Feature requests are welcome.
If you would love to have something new in this projet, or if you want to code it yourself, please :
- take a look to our roadmap,
- search for existing issues about this feature,
- if there is no issue for your need, please open an issue asking for feedback. It is really important before starting any implementation. Otherwise, you risk spending a lot of time working on something that the the project's developers might not want to merge into the project.
When using the issue tracker, you will have an issue template for features. Please, fill in what you can. It will be an area of discussions between you and the project's developers.
But take a moment to find out whether your idea fits within the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible.
Improving documentation or writing tutorials are all examples of helpful contributions that make us thankful. It is a good way to discover the project and its community.
We really appreciate the community picking up and fixing bugs or even implementing new features. As said before, following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, we should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
To get started, you will need to have git, docker and docker-compose installed locally. The last two are used for tests.
Fork the project on GitHub and clone your fork locally :
git clone [email protected]:username/route-graph-generator.git
cd route-graph-generator
git remote add upstream https://github.com/IGNF/route-graph-generator.git
git pull upstream
Don't forget to configure git so that it knows who you are :
git config user.name "Random User"
git config user.email "[email protected]"
You can use any name/email address you prefer here. We only use the metadata generated by git using this configuration for properly attributing your changes to you in the AUTHORS file and the changelog.
If you would like for the GitHub UI to link the commit to your account and award you the Contributor label after the changes have been merged, make sure this local email is also added to your GitHub email list.
As a best practice to keep your development environment as organized as possible, create local branches to work within. When you create a branch, do it directly off of the upstream develop branch.
git checkout upstream develop
git checkout -b my-branch
Please, create one branch (so one Pull Request) per feature or fix.
The branch name depends on the contribution you want to do :
doc/*for modifying or adding docs only,feat/*for coding new functionnalities,fix/*for fixing the code,docker/*for modifying the docker part only,test/*for modifying or adding tests only,ci/*for modifying or adding Github CI only
Modifying route-graph-generator (r2gg) typically involves changes to one or more of a few places in the repository.
- Python code contained in the
/srcdirectory, - SQL code contained in the
/sqldirectory, - Documentation in
/docsdirectory and in possibly the/readme.md, - Tests within the
/testsdirectory, - Dockerfiles and configuration in
/dockerdirectory, - the
/changelog.mdmust be updated.
Route-graph-generator is coded in Python 3.
Let's dive into some specificities of this project.
Comment the code as much as possible to facilitate its understanding.
There are different levels of logs. You can use each of them. The easiest way is to take a look at what is currently being done in the code.
A SQL script will only be added if the concerned format is widely used by a strong community.
A format will only be added if the concerned format is widely used by a strong community.
It is a best practice to keep your changes as logically grouped as possible within individual commits. There is no limit to the number of commits any single pull request may have, and many contributors find it easier to review changes that are split across multiple commits.
git add my/changed/files
git commit -m "[type of change] explicit change"
Note that multiple commits often will get squashed when they are landed.
As a best practice, once you have committed your changes, it is a good idea to use git rebase (not git merge) to synchronize your work with the main repository.
git checkout upstream develop
git pull upstream develop
git checkout my-branch
git rebase develop
This ensures that your working branch has the latest changes from the develop branch of the origin repository. Moreover, your Pull Request will be easier to merge.
Bug fixes and features should always come with tests.
There are not a lot of tests in this project. Help is needed by the way. ;)
The /tests directory contains :
- functionnal tests : those tests must all be validated. To run them, you can see this doc.
Once you are sure your commits are ready to go, with passing tests, begin the process of opening a pull request by pushing your working branch to your fork on GitHub.
git push origin my-branch
From within GitHub, opening a new pull request will present you with a pull request template. Please, try to do your best at filling out the details, but feel free to skip parts if you're not sure what to put.
Once opened, pull requests are usually reviewed within a few days.
To get feedback on your proposed change even though it is not ready to land, use the Convert to draft option in the GitHub UI instead of the wip label.
Breaking changes need to have a BREAKING prefix.
You will probably get feedback or requests for changes to your pull request. This is a big part of the submission process so don't be discouraged! Some contributors may sign off on the pull request right away, others may have more detailed comments or feedback. This is a necessary part of the process in order to evaluate whether the proposed changes are correct and necessary.
To make changes to an existing pull request, make the changes to your local branch, add a new commit with those changes, and push those to your fork. GitHub will automatically update the pull request.
git add my/changed/files
git commit
git push origin my-branch
If a git conflict arises, it is necessary to synchronize your branch with other changes that have landed upstream by using git rebase:
git checkout upstream develop
git pull upstream develop
git checkout my-branch
git rebase develop
git push --force origin my-branch
Important: The git push --force command is one of the few ways to delete history in git. It also complicates the review process, as it won't allow reviewers to get a quick glance on what changed. Before you use it, make sure you understand the risks. If in doubt, you can always ask for guidance in the pull request.
There are a number of more advanced mechanisms for managing commits using git rebase that can be used, but are beyond the scope of this guide.
All pull requests require "sign off" in order to land. Whenever a contributor reviews a pull request they may find specific details that they would like to see changed or fixed. These may be as simple as fixing a typo, or may involve substantive changes to the code you have written. While such requests are intended to be helpful, they may come across as abrupt or unhelpful, especially requests to change things that do not include concrete suggestions on how to change them.
Try not to be discouraged. If you feel that a particular review is unfair, say so, or contact one of the other contributors in the project and seek their input. Often such comments are the result of the reviewer having only taken a short amount of time to review and are not ill-intended. Such issues can often be resolved with a bit of patience. That said, reviewers should be expected to be helpful in their feedback, and feedback that is simply vague, dismissive, and unhelpful is likely safe to ignore.
In order to land, a pull request needs to be reviewed and approved by at least two administrators and pass a CI (Continuous Integration) test run.
When an administrator lands your pull request, GitHub might show the pull request as Closed at this point, but don't worry. If you look at the branch you raised your pull request against, you should see a commit with your name on it. Congratulations and thanks for your contribution!