5. Welcome to our contributing guide#

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.

5.1. Report bugs#

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.

5.2. Request new features#

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.

5.3. No-Code contributions#

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.

5.4. Code contributions#

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.

5.5. Pull Requests#

5.5.1. Setting up your local environment#

To get started, you will need to have git, docker and docker-compose installed locally. The last two are used for tests.

5.5.1.1. Step 1 : Fork#

Fork the project on GitHub and clone your fork locally :

git clone git@github.com:username/road2.git
cd road2
git remote add upstream https://github.com/IGNF/road2.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 "random.user@example.com"

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.

5.5.1.2. Step 2 : Branch#

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.

5.5.1.2.1. Branch name guidelines#

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

5.5.2. The process of making changes#

5.5.2.1. Step 3 : Code#

Modifying Road2 typically involves changes to one or more of a few places in the repository.

  • JavaScript code contained in the /src directory,

  • Documentation in /documentation directory and in possibly the /readme.md,

  • Tests within the /test directory,

  • Dockerfiles and configuration in /docker directory,

  • the /changelog.md must be updated.

5.5.2.1.1. Code guidelines#

Road2 is coded in Javascript, according to ES6 features.

Let’s dive into some specificities of this project.

5.5.2.1.1.1. Variables#

Variables are camel cased.

Use let most of the time and avoid var. Use const only for constants (including objects). It is a way to say “I create this object to be constant, so don’t change it”.

5.5.2.1.1.2. Functions#

Avoid unused functions.

5.5.2.1.1.3. Classes#

Create a class most of the time. If you are not sure, ask us in the issue concerning your dev.

When you create a classe, use get and set keywords to indicate which attributes are exposed, editable, or not.

When you are using a class instance, respect its attributes (getters/setters). Avoid adding a propertie to an instance. It is better to modify a class or create a child one. For this type of modification, please, talk to us before your dev. It will avoid frustration if those modifications are not in the ways of the project.

5.5.2.1.1.4. Asynchronism#

Don’t make callbacks but promises.

If you use a library with callbacks, encapsulate each one in its promise.

We make Promises at the lowest level and then we only manage with async/await/try/catch in order to have a code that is easier to understand and easier to maintain. The try/catch only takes place at the second level, the one using the lowest level returning a Promise. Thus, all higher levels are not at risk of having an unexpected error, but they simply manage the return of the function of level N-1. This allows you to fully understand what is happening, especially in the case of script-type actions that have an impact on the state of the service.

5.5.2.1.1.5. Try/catch#

Use try/catch as much as possible in order to control errors and the rest of the code execution. This ensures that a function always returns what it is supposed to return and that there is no unexpected error.

5.5.2.1.1.6. Comments#

Comment the code as much as possible to facilitate its understanding.

5.5.2.1.1.7. Logs#

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.

For instance, fatal is reserved for a shutdown of the server,error for an unexpected error, warn for a non-problematic event, info is the most used level, and debug is useful for adding a lot of informations like object content.

5.5.2.1.1.8. Engines#

Engines are only added if they are widely used by a strong community and provide functionality not available elsewhere.

5.5.2.1.1.9. APIs#

Since it is easy to add an API from a different Github project, we will only add APIs from standards, such as those from the OGC.

5.5.2.2. Step 4 : Commit#

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.

5.5.2.3. Step 5 : Rebase#

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.

5.5.2.4. Step 6 : Test#

Bug fixes and features should always come with tests.

There are a lot of tests in this project. They are written to be run with the docker-compose of the project.

The /test directory contains :

  • unit tests : those tests must all be validated.

  • integration tests : it is a WIP so create or update, and run the tests concerned by your developments.

  • functionnal tests : those tests must all be validated. To run them, you will have to generate data.

5.5.2.5. Step 7 : Push#

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

5.5.2.6. Step 8 : Opening the Pull Request#

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.

5.5.2.7. Step 9 : Discuss and update#

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.

5.5.2.8. Step 10 : Landing#

In order to land, a pull request needs to be reviewed and approved by at least two Road2 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!