15 KiB

Raw Permalink Blame History

Introduction

Interested in developing new features, fixing bugs, or making any other kind of contribution which touches Gazebo's codebase? Read on to find out how!

Development process

We follow a development process designed to reduce errors, encourage collaboration, and make high quality code. The process may seem rigid and tedious, but every step is worth the effort.

Steps to follow

Are you sure?

Run through this mental checklist before getting started.
1. Has your idea already been done, or maybe someone is already working on it?
  
  Check answers.gazebosim.org and the issue tracker.
2. Get feedback from the Gazebo core team.
  
  Send an email to the mailing list, post a question on Gazebo Answers, or use the issue tracker to get feedback from Gazebo developers.
Fork Gazebo

This will create your own personal copy of Gazebo. All of your development should take place in your fork.
Choose a base branch

If your changes will break API or ABI, then base your new branch off of default. If your changes don't break API/ABI and you would like them to be released to an existing gazebo release with major version N, then use branch gazeboN as the base.
Work out of a branch

Always work out of a new branch, never off of the base branch. This is a good habit to get in, and will make your life easier.
Write your code.

This is the fun part.
Write tests

In most cases, a pull request will only be accepted if it has tests. See the "Write tests" section below for more information.
Compiler warnings

Code must have zero compile warnings, or at least make sure your pull request is not adding new warnings.
Style

Static code checking analyzes your code for bugs, such as potential memory leaks, and style. Gazebo's static code checker uses cppcheck, and a modified cpplint. You'll need to install cppcheck on your system. Ubuntu users can install via:
```
 sudo apt-get install cppcheck
```
To check your code, run the following script from the root of the Gazebo sources:
```
 sh tools/code_check.sh
```
It takes a few minutes to run. Fix all errors and warnings until the output looks like:
```
 Total errors found: 0
```
The tool does not catch all style errors. See the "Style" section below for more information.
Tests pass

There must be no failing tests. You can check by running make test in your build directory.

Running all tests in Gazebo may take a long time. If you expect your changes to only affect a few different tests, it should be enough to run each one of them individually from the build directory, for example:
```
 ./test/integration/INTEGRATION_world
```
Documentation.

Document all your code. Every class, function, member variable must have doxygen comments. All code in source files must have documentation that describes the functionality. This will help reviewers and future developers.
Review your code.

Before submitting your code through a pull request, take some time to review everything line-by-line. The review process will go much faster if you make sure everything is perfect before other people look at your code. There is a bit of the human-condition involved here. Folks are less likely to spend time reviewing your code if it's sloppy.
Small pull requests

A large pull request is hard to review, and will take a long time. It is worth your time to split a large pull request into multiple smaller pull requests. For reference, here are a few examples:
Make a pull request

Submit a pull request when you're ready.
Continuous integration

The moment you make a pull request, a few jobs in our continuous integration server will be started. These jobs will build your branch on Linux, Mac and Windows, run all tests and check for warnings.

Your pull request will be updated with the status of these builds. Take some time to check these builds and see if you've introduced test failures, warnings or broke some build. If you did and know how to fix it, do so. If you don't know, speak up and someone may try to help you.
Review

At least two other people have to approve your pull request before it can be merged. Please be responsive to any questions and comments.
Done, phew.

Once you have met all the requirements, you're code will be merged. Thanks for improving Gazebo!

Internal Developers

This section is targeted mostly at people who have commit access to the main repositories.

In addition to the general development process, please follow these steps before submitting a pull request. Each step is pass/fail, where the test or check must pass before continuing to the next step.

Run the style checker on your personal computer
Run all, or only relevant, tests on your personal computer
Run your branch through a Jenkins Linux no-gpu build
Run your branch through a Jenkins Linux Nvidia build
Run your branch through a Jenkins Homebrew build
Run your branch through a Jenkins Windows build
Run your branch through the ABI/API checker if targeting a release branch
Submit the pull request, and make sure the following are included (a set of jenkins jobs will run automatically once the pull request is created, if not included automatically, you must add them manually):
Link to a coverage report
Link to a passing Homebrew build
Link to a passing Linux no-gpu build
Link to a passing Linux Nvidia build
Link to a passing Windows build
Link to a passing ABI/API report if the pull request is targeted at a release branch

Style

In general, we follow Google's style guide. However, we add in some extras.

This pointer

All class attributes and member functions must be accessed using the this-> pointer. Here is an example.

Underscore function parameters

All function parameters must start with an underscore. Here is an example.

Do not cuddle braces

All braces must be on their own line. Here is an example.

Multi-line code blocks

If a block of code spans multiple lines and is part of a flow control statement, such as an if, then it must be wrapped in braces. Here is an example

++ operator

This occurs mostly in for loops. Prefix the ++ operator, which is slightly more efficient than postfix in some cases.

PIMPL/Opaque pointer

If you are writing a new class, it must use a private data pointer. Here is an example, and you can read more here.

const functions

Any class function that does not change a member variable should be marked as const. Here is an example.

const parameters

All parameters that are not modified by a function should be marked as const. This applies to parameters that are passed by reference, pointer, and value. Here is an example.

Pointer and reference variables

Place the * and & next to the varaible name, not next to the type. For example: int &variable is good, but int& variable is not. Here is an example.

Camel case

In general, everything should use camel case. Exceptions include SDF element names, and protobuf variable names. Here is an example.

Class function names

Class functions must start with a capital letter, and capitalize every word.

void MyFunction(); : Good

void myFunction(); : Bad

void my_function(); : Bad

Variable names

Variables must start with a lower case letter, and capitalize every word thereafter.

int myVariable; : Good

int myvariable; : Bad

int my_variable; : Bad

No inline comments

// style comments may not be placed on the same line as code.

speed *= 0.44704; // miles per hour to meters per second : Bad

Write tests

Gazebo uses GTest for general testing and QTest for GUI tests. There are a few kinds of tests:

Unit tests: all classes should have corresponding unit tests. These live in the same directory as the source code and are prefixed by _TEST.
Integration tests: tests which verify how many classes are working together go under the tests/integration directory.
Regression tests: tests which fix broken features go under tests/regression and are prefixed by the issue number on Gazebo's issue tracker.

Before creating a new integration or regression test file, check the current test files. If one closely matches the topic of your new code, simply add a new test function to the file. Otherwise, create a new test file, and write your test.

Test coverage

The goal is to achieve 100% line and branch coverage. However, this is not always possible due to complexity issues, analysis tools misreporting coverage, and time constraints. Try to write as complete of a test suite as possible, and use the coverage analysis tools as guide. If you have trouble writing a test please ask for help in your pull request.

Gazebo has a build target called make coverage that will produce a code coverage report. You'll need to have lcov and gcov installed.

In your build folder, compile Gazebo with -DCMAKE_BUILD_TYPE=Coverage
```
 cmake -DCMAKE_BUILD_TYPE=Coverage ..\
 make
```
Run a single test, or all the tests
```
 make test
```
Make the coverage report
```
 make coverage
```
View the coverage report
```
 firefox coverage/index.html
```

Gazebo assertions

What is an assertion?

An assertion is a check, which always produces a boolean result, that developers place in the code when want to be sure that check is always true. They are aimed to detect programming errors and should check for impossible situations in the code. If the assertion check failed, the assertion will stop the program immediately.

 Object * p = some_crazy_function()
 GZ_ASSERT(p != nullptr, "Object from some_crazy_function should never point to NULL")
 p->run()

Gazebo runtime assertions: GZ_ASSERT

In Gazebo, the GZ_ASSERT macro id designed to handle all our runtime assertions

 GZ_ASSERT(<condition to check>,<fail msg>)

condition-to-check: anything returning a boolean value that should always be true.
fail msg: message displayed when assertion is thrown

Benefits of the assertions

Some of the benefits of using the assertions:

They are really useful for not having to debug all kind of weird and unexpected errors, especially in runtime. Exact failure point appears when pass by an assertion.
Developer can be sure that some conditions are met at a given code point. Code turns more reliable.
Help to detect no so obvious errors happening (affecting performance for example)

Difference between Assertion and Exception

While assertions are aimed at impossible situations generated from programming errors, exceptions handle all kind of expected errors and unusual but logically possible code situations.

Lets review an example: suppose we are writing a math library and created a really fast method to calculate square roots but it only works for positive numbers. Something declared as:

 double sqrt_for_positives(double number)

So what could be an assertion and what an exception for our revolutionary function?

Exception: if the incoming number is negative (our function only accepts positive numbers), then we will thrown an exception. It was an error by the user but we should consider it a possible scenario since we are offering a public interface.
Assertion: our square root should never return a negative number. This is not a logical error, it's a completely unexpected error.

Debugging Gazebo

Meaningful backtraces

In order to provide meaningful backtraces when using a debugger, such as GDB, Gazebo should be compiled with debugging support enabled. When using the ubuntu packages, specially the ''-dbg'' package, this support is limited but could be enough in most of the situations. This are the three level of traces which can be obtained:

Maximum level of debugging support :This only can be obtained compiling Gazebo from source and setting the CMAKE_BUILD_TYPE to DEBUG. This will set up no optimizations and debugging symbols. It can be required by developers in situations specially difficult to reproduce.

Medium level of debugging support :This can be obtained installing the ''gazebo-dbg'' package (since 1.4 version) or compiling Gazebo from source using the RELWITHDEBINFO CMAKE_BUILD_TYPE mode (which is the default if no mode is provided). This will set up ''-O2'' optimization level but provide debugging symbols. This should be the default when firing up gdb to explore errors and submit traces.

Minimum level of debugging support :This one is present in package versions previous to 1.4 (no ''-dbg'' package present) or compiling Gazebo from source using the RELEASE CMAKE_BUILD_TYPE option. This will set up the maximum level of optimizations and does not provide any debugging symbol information. This traces are particularly difficult to follow.

15 KiB Raw Permalink Blame History