Contributing
We use GitHub to ensure good workflow in our software team. It goes as follows:
- Find an issue to work on
- Make a branch for your issue
git checkout -b branch_name - Commit changes you make to the code to that branch. Make many small commits to clarify the progress.
git commit -sm "commit message" - Push your changes after every work session (at least!).
git push - When the issue is solved, make a pull request and link it to the issue. Assign relevant people (at least one) as code reviewers. Discuss the changes with the reviewer and make improvements.
- When the pull request is accepted the the issue is closed automatically.
A slightly more visual explanation of the workflow can be found on this feature page.
The workflow leans heavily on issues for keeping track of tasks and their progress. They are explained in this GitHub guide.
Before code you write is accepted into the project, it has to pass a code review. This is done through Pull Requests by simply adding one or more code reviewers to the pull request.
The following are examples of the established naming practice:
development
feature/camera_centering_pid
improvement/better_controller_tuning
bugfix/weird_mission_behaviour
When creating a new branch to work on a specific issue, tag the related issue(s) in the first commit. Every issue on GitHub will have a #<number> attached to it (can be found after the issue title). The first commit message would therefore look something like:
addressing issue #<number>
Once you have created your own branch, you can practically do whatever you like to it, without causing any problems in the master and development branches. However, there are a few things to keep in mind when it comes to committing:
- It is seen as bad practice to commit code that does not function
- Even worse is to commit code that does not compile
- A good commit message describes what changes the commit makes, eg:
cleans up launch file structure
- For smaller fixes, typically a detail that was forgotten on the last commit, write a message like
debug: <what small thing this commit fixes>
- Once you have committed many changes locally, it might be a good idea to push your commits to your branch on GitHub. This ensures that your progress is not lost in the event of data loss on your own end.
Every package should contain a readme. The content of the readme should follow, but is not limited to, the following template:
# <name of package>
Description of what this package is, does, and why it is needed.
## Setup instructions
Some good instructions on what parameters need to be set and why
## Inputs and outputs
List of topics/actions/services this package provides or uses
All dependencies are kept in files to make it easy to keep track of:
- External repository dependencies are kept in .repos files. To install these, you may run
vcs import --skip-existing --input filename.repos - Apt package dependencies can be found in the packages.txt file. To install all of these at once, you may run
xargs -a packages.txt sudo apt-get install. Alternatively you may install them individually as you please. - Python dependencies are kept in the requirements.txt file. To install these you may run
pip install -r requirements.txt