Skip to content

Latest commit

 

History

History
182 lines (124 loc) · 5.71 KB

CONTRIBUTE.md

File metadata and controls

182 lines (124 loc) · 5.71 KB
Raw

This section explains how to setup your development environment and gives you some basic advice on how to contribute to the project.

Table of contents

IDE

Visual Studio Code

I develop under VSC but development environments may be used.

Installation

Windows:

Download installer from here and install.

Linux:

sudo snap install --classic code

Required Extensions

  • PlatformIO IDE : To compile, test and upload programs to Arduino (and other boards).

    code --install-extension platformio.platformio-ide

  • C/C++ : Language support for VSC.

    code --install-extension ms-vscode.cpptools

Optional Extensions

Hererunder a list of useful extensions I use for this project:

  • Doxygen Documentation Generator : Handy extension to generated automatically a doxygen placeholder comment when typing /** before a function.

    code --install-extension cschlosser.doxdocgen

  • Github Extension : Useful to view issues and pull requests from the project repository directly inside VSC.

    code --install-extension GitHub.vscode-pull-request-github

  • PlantUML : Used to create and generate UML diagrams. This extension requires Java and Graphviz to be installed. I would also recommend to use the SVG extension to view generated diagrams that were exported as SVG.

    On Windows:

    choco install graphviz

    On Ubuntu:

    sudo apt install java
sudo apt install graphviz

    On both:

    code --install-extension jebbs.plantuml
code --install-extension jock.svg

  • Markdown All in One : Markdown syntax highlighting, automatic table of content generation and shortcuts. I also recommend to install Markdown Lint to verify if the Markdown syntax is correct and the Enhanced Markdown preview.

    code --install-extension yzhang.markdown-all-in-one
code --install-extension DavidAnson.vscode-markdownlint
code --install-extension shd101wyy.markdown-preview-enhanced

  • TODO Tree : To track TODO and FIXME comments in the code.

    code --install-extension gruntfuggly.todo-tree

Project Documentation

General

A good entry point to understand the overal software design of the robot:

TODO Add links to other pages

Diagrams

Diagrams are created with PlantUML.

Documentation:

Coding rules

Documentation with Doxygen

The source code should be documentetd with Doxygen tags. Hereunder an example of a Doxygen file header:

/**
 * @file SharpDistSensorArray.h
 * @author Mike Margreve ([email protected])
 * @brief This library manages the 3 Sharp distance sensors on the robot
 * @version 1.0
 * @date 2020-04-25
 */

Functions are documented in a similar way:

/**
 * @brief Re-maps a number from one range to another (floating point variant).
 *
 * That is, a value of fromLow would get mapped to toLow,
 * a value of fromHigh to toHigh, values in-between to values in-between, etc.
 *
 * @param value the number to map.
 * @param fromLow the lower bound of the value’s current range.
 * @param fromHigh the upper bound of the value’s current range.
 * @param toLow the lower bound of the value’s target range.
 * @param toHigh the upper bound of the value’s target range.
 * @return The mapped value.
 */
float mapFloat(float value, float fromLow, float fromHigh, float toLow, float toHigh);

An exhaustive list of Doxygen tags can be found in the documentation.

Git

Clone the repository:

git clone https://github.com/margrevm/trollbot.git

Workflow

The project uses the Gitflow workflow for branch management. More information about how this works can be found in this tutorial.

Basically there are three types of branches:

  • The master branch for releases.
  • The dev branch for development which contains the current stable build (tested with TravisCI).
  • feature/<feature> branches which are based on the dev branch and contain changes for each new feature. Once a feature is finished, it is merged to dev.

Committing

  • When committing, please add the reference of the corresponding issue #XXX to the message.
  • Issues can be automatically closed with close, closes, closed, fixes or fixed keywords in the message.

More documentation about the Github issue management can be found on the GitHub Blog.

Thanks for contributing!