8.0 KiB
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
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.
2. Read the docs. Make sure that the issue is a bug, not a misunderstanding on how is CARLA supposed to work. Read the pages related to the issue in the Documentation and take a look at the FAQ page.
Request features
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.
Code contributions
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 carla.simulator@gmail.com).
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.
Coding standard
Follow the current coding standard when submitting new code.
Submission
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
devnamed asusername/name_of_the_contribution. - 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.
Checklist
- 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
make check.
Art contributions
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.
4. Build CARLA. In order to contribute, a CARLA build is necessary. Follow the instructions to build either in Linux or Windows.
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.
Docs contributions
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.
The documentation is written with a mix of Markdown and HTML tags, with a some extra CSS code for features such as tables or the town slider. Follow the steps below to start writing documentation.
!!! Important
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.
1. Build CARLA from source. Follow the steps in the docs to build on Linux or Windows.
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.
mkdocs serve
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.
!!! Warning
The local repository must be updated with the latest updates in the dev branch.