.. _contributing: 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. .. _version-control: 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 Repository structure ```````````````````` File structure """""""""""""" * ``./docker/`` This directory contains everything needed for building and running the as docker image, see :ref:`docker` for more details. * ``./docs/`` This directory contains everything for documenting the project, as well as building and viewing the documentation, see :ref:`write-docs` for more details. * ``./foxglove_panels/`` This directory contains all prepared and shared dashboards for the AS ROS system for foxglove, see :ref:`visualizer` 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 :ref:`gui-in-container` and :ref:`vscode` 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 Cloning ``````` Before you can clone the repository, you need to install git on your system .. tab:: Ubuntu .. code:: bash sudo apt install git .. tab:: Windows Download the `git installer `_ and install it. 1. If you clone the repository via https a. Generate a personal access token from `GitLab `_ and copy it b. Store the personal access token, so it must not be reentered every time (unsafe, but still recommended :/) .. code:: bash git config credential.helper store 2. Clone the AS ROS git repository .. code:: bash 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. 3. Remember to update the submodules with the same command everytime you switch branches, since they may differ from branch to branch .. code:: bash git submodule update --init --recursive Branch Organization ``````````````````` We normally have three types of branches: #. ``main`` branch: Holds the most recent and most extensive tested software version which will run the most reliable ontrack. #. ``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. #. ``feature/`` 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: .. code-block:: bash git checkout -b feature/ 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 (:ref:`create-pull-request`). .. _create-pull-request: 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: #. Add atleast two a Approvers. #. Contain a descriptive summary of your changes. #. Contain instructions how to test your changes. #. Your Code needs to fulfill the Style Guide. #. The documentation should be updated to represent your changes. You should also check all the things, that a Approver will have to do. Approving a pull request ```````````````````````` To approve a pull request, you should: #. Check whether the docker container will still succesfully build without cache. #. Check whether the pipeline will still run (all disciplines), see :ref:`debug-pipeline`. #. Check whether the Code follows the Style Guide for the respective language. #. Check whether the documentation is up to date. #. Check whether the written Code is clean. Style Guide for Code -------------------- Since code is read much more often than it is written, it is important to use a constintent Style Guide. 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 (:ref:`docker`) and the Instructions for using it with VSCode (:ref:`vscode-as-ros-container`) 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. .. _PEP8 Style Guide: https://peps.python.org/pep-0008/ .. _type hints: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html Style Guide for C/C++ ````````````````````` .. todo:: Research and add Style Guide for C/C++ .. _personal access token for bitbucket: https://bitbucket.curemannheim.de/plugins/servlet/access-tokens/manage