Contributing to CARLA
The CARLA team is glad to accept contributions from anybody willing to collaborate. There are different ways to contribute to the project, depending on the capabilities of the contributor. The team will work as much as possible so that contributions are successfully integrated in CARLA.
Take a look and don't hesitate!
- Report bugs
- Request features
- Code contributions
- Art contributions
- Docs contributions
Issues can be reported in the issue section on GitHub. Before reporting a new bug, make sure to do some checkups.
1. Check if the bug has been reported. Look it up in that same issue section on GitHub.
Ideas for new features are also a great way to contribute. Any suggestion that could improve the users' experience can be submitted in the corresponding GitHub section here.
Before starting hands-on on coding, please check out the issue board to check what is the team already working on, to avoid overlapping. In case of doubt or to discuss how to proceed, please contact one of us (or send an email to firstname.lastname@example.org).
Learn about Unreal Engine
A basic introduction to C++ programming with UE4 can be found at Unreal's C++ Programming Tutorials. There are other options online, some of them not free of charge. The Unreal C++ Course at Udemy it's pretty complete and there are usually offers that make it very affordable.
Before getting started
Check out the CARLA Design document to get an idea on the different modules that compose CARLA. Choose the most appropriate one to hold the new feature. Feel free to contact the team in the Discord server in case any doubt arises during the process.
Follow the current coding standard when submitting new code.
Contributions and new features are not merged directly to the
master branch, but to an intermediate branch named
dev. This Gitflow branching model makes it easier to maintain a stable master branch. This model requires a specific workflow for contributions.
- Always keep your
devbranch updated with the lastest changes.
- Develop the contribution in child branch from
- Once the contribution is ready, submit a pull-request from your branch to
dev. Try to be as descriptive as possible when filling the description. Note that there are some checks that the new code is required to pass before merging. The checks are automatically run by the continuous integration system. A green tick mark will appear if the checks are successful. If a red mark, please correct the code accordingly.
Once the contribution is merged in
dev, it can be tested with the rest of new features. By the time of the next release, the
dev branch will be merged to
master, and the contribution will be available and announced.
- [ ] Your branch is up-to-date with the
devbranch and tested with latest changes.
- [ ] Extended the README/documentation, if necessary.
- [ ] Code compiles correctly.
- [ ] All tests passing with
Art contributions include vehicles, walkers, maps or any other type of assets to be used in CARLA. These are stored in a BitBucket repository, which has some account space limitations. For said reason, the contributor will have to get in touch with the CARLA team, and ask them to create a branch on the content repository for the contributions.
1. Create a BitBucket account. Visit the Bitbucket page.
2. Contact the art team to get access to the content repository. Join the Discord server. Go to the Contributors channel and request for access to the content repostory.
3. A branch will be created for each contributor. The branch will be named as
contributors/contributor_name. All the contributions made by said user should be made in that corresponding branch.
5. Download the content repository. Follow the instructions to update the content in here.
6. Update the branch to be in sync with master. The branch should always be updated with the latest changes in master.
7. Upload the contribution. Do the corresponding changes and push the branch to origin.
8. Wait for the art team to check it up. Once the contribution is uploaded, the team will check that everything is prepared to be merged with master.
If some documentation is missing, vague or imprecise, it can be reported as with any other bug (read the previous section on how to report bugs). However, users can contribute by writing documentation.
To submit docs contributions, follow the same workflow explained right above in code contributions. To sum up, contributions are made in a child branch from
dev and merged to said branch.
2. Install MkDocs. MkDocs is a static site generator used to build documentation.
sudo pip install mkdocs
3. Visualize the docs. In the main CARLA folder, run the following command and click the link that appears in the terminal (http://127.0.0.1:8000) to open a local visualization of the documentation.
4. Create a git branch. Make sure to be in the
dev branch (updated to latest changes) when creating a new one.
git checkout -b <contributor_name>/<branch_name>
5. Write the docs. Edit the files following the guidelines in the documentation standard page.
6. Submit the changes. Create a pull request in the GitHub repository, and add one of the suggested reviewers. Try to be as descriptive as possible when filling the pull-request description.
7. Wait for review. The team will check if everything is ready to be merged or any changes are needed.
The local repository must be updated with the latest updates in the