1.2. How to contribute

Contributing is rather simple. Follow the Sytle Guide for your Language, develop on a feature branch and make a pull request to merge your developed feature onto dev.

1.2.1. Version Control

As you must know, since you read the documentation there, we use git as Version Control with GitLab as git backend.

To contribute, you have to clone the repository. See below for details

1.2.1.1. Repository structure

1.2.1.1.1. File structure

  • ./docker/

    This directory contains everything needed for building and running the as docker image, see Our Docker Environment Explained for more details.

  • ./docs/

    This directory contains everything for documenting the project, as well as building and viewing the documentation, see How to write Docs for more details.

  • ./foxglove_panels/

    This directory contains all prepared and shared dashboards for the AS ROS system for foxglove, see Creating Visualization for recorded Rosbags for more details.

  • ./logs/

    This directory mounts the ROS log directories of every running AS ROS docker container.

  • ./rosbags/

    This directory gets mounted into every running AS ROS docker container (/workspace/as_ros/rosbags) to enable file exchange for rosbags, drone footage or paramaters.

  • ./src/

    This directory contains the catkin workspace and thus all source code for the Autonomous System. This directory also gets mounted into all running docker containers, so that you do not have to rebuild the docker container when changing some code.

  • ./utils

    This directory contains different utility scripts, e.g. for installing all necessary VSCode extensions on the host system, see Using GUIs inside an AS ROS container and Visual Studio Code as standardized IDE

1.2.1.1.2. Submodules

This (AS ROS repository) does not work standalone, since it relies on multiple other git repositories. This dependency is implemented via git submodules.

  • Electronics/PER mounted under src/can_interface/dbcs/per

    DBC File for interpreting the CAN messages on the periphery CAN bus.

  • Electronics/LOG mounted under src/can_interface/dbcs/log

    DBC File for interpreting the CAN messages on the logging CAN bus.

  • Driverless/SLAM mounted under src/slam

    Self implemented ROS package for SLAM.

  • Driverless/zed-ros-wrapper mounted under src/zed-ros-wrapper

    Forked zed ros wrapper with custom configuration.

  • Driverless/ouster-ros mounted under src/ouster_ros_driver

    Forked ouster ros driver with custom configuration

  • alspitz/cpu_monitor mounted under src/cpu_monitor

    Public Github repository

1.2.1.2. Cloning

Before you can clone the repository, you need to install git on your system

sudo apt install git

Download the git installer and install it.

  1. If you clone the repository via https

    1. Generate a personal access token from GitLab and copy it

    2. Store the personal access token, so it must not be reentered every time (unsafe, but still recommended :/)

      git config credential.helper store

  2. Clone the AS ROS git repository

    git clone https://YOUR_PERSONAL_ACCESS_TOKEN@gitlab.curemannheim.de/driverless/as_ros.git && cd as_ros

Make sure to replace YOUR_PERSONAL_ACCESS_TOKEN with your actual token.

  1. Remember to update the submodules with the same command everytime you switch branches, since they may differ from branch to branch
    git submodule update --init --recursive

1.2.1.3. Branch Organization

We normally have three types of branches:

  1. main branch: Holds the most recent and most extensive tested software version which will run the most reliable ontrack.

  2. dev branch: Holds the most recent development version which has been tested fairly extensive, runs reliable in simulations and should run reliable ontrack. The code documentation should also be up to date and the Style Guide should be followed.

  3. feature/<name> branches: Hold a version that you actively developing a new feature. The Code has not be tested, the documentation can be outdated and the Style Guide must not be followed yet, though it is recommended.

Bitbucket should prevent you from pushing directly onto master & dev and in general from force pushing anything.

Thus, when you want to develop a new feature, you switch to the dev branch or some other useful feature branch. From there you create a new feature branch:

git checkout -b feature/<name>

You can now develop your new feature.

When you think you are ready, ensure that you follow the Sytle Guide and your new feature is tested and create a pull request (Creating a pull request).

1.2.1.4. Creating a pull request

At this moment, we recommend to create the Pull Request on the web interface of bitbucket.

Your Pull Request needs to fulfill the following requirements:

  1. Add atleast two a Approvers.

  2. Contain a descriptive summary of your changes.

  3. Contain instructions how to test your changes.

  4. Your Code needs to fulfill the Style Guide.

  5. The documentation should be updated to represent your changes.

You should also check all the things, that a Approver will have to do.

1.2.1.5. Approving a pull request

To approve a pull request, you should:

  1. Check whether the docker container will still succesfully build without cache.

  2. Check whether the pipeline will still run (all disciplines), see Test the pipeline for driving a mission.

  3. Check whether the Code follows the Style Guide for the respective language.

  4. Check whether the documentation is up to date.

  5. Check whether the written Code is clean.

1.2.2. Style Guide for Code

Since code is read much more often than it is written, it is important to use a constintent Style Guide.

1.2.2.1. Style Guide for Python

For Python we decided to follow (at least most of the times) the PEP8 Style Guide of Python.

The docker container (Our Docker Environment Explained) and the Instructions for using it with VSCode (Connect to an AS ROS container with VSCode) contain everything to follow them: We use the python linter flake8 to lint the python files accordingly.

We also decided to use type hints within python when it is applicable and possible.

We also decided to write docstrings for nearly every module, class and function.

We decided to use single quotation marks for strings.

This will be all verified by flake8 and respective errors, warnings and infos will be shown in the Problems View of VSCode.

1.2.2.2. Style Guide for C/C++

Todo

Research and add Style Guide for C/C++