How to contribute

Ignition Transport is an open source project based on the Apache License Version 2.0, and is maintained by hardworking developers for everyone’s benefit. If you would like to contribute software patches, read on to find out how. You’ll probably want to check out the Development Section for learning about the internal design of the library when planning your contribution.

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 (especially if you like applications that work).

Steps to follow

  1. Are you sure? Has your idea already been done, or maybe someone is already working on it?
Check the issue tracker.

2. Fork Ignition Transport. This will create your own personal copy of the project. All of your development should take place in your fork.

  1. Work out of a branch:
hg branch my_new_branch_name

Always work out of a new branch, never off of default. This is a good habit to get in, and will make your life easier. If you’re solving an issue, make the branch name issue_ followed by the issue number. E.g.: issue_23.

  1. Write your code.
This is the fun part.
  1. Write tests.
A pull request will only be accepted if it has tests. See the Test coverage section below for more information.
  1. Compiler warnings.
Code must have zero compile warnings. This currently only applies to Linux.
  1. Style.
A tool is provided to check for correct style. Your code must have no errors after running the following command from the root of the source tree:
sh tools/code_check.sh

The tool does not catch all style errors. See the Style section below for more information.

  1. Tests pass.
There must be no failing tests. You can check by running make test in your build directory.
  1. 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.
  1. 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 bad.
  1. 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:

  1. Pull request.
Submit a pull request when you ready.
  1. 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.
  1. Done, phew.
Once you have met all the requirements, you’re code will be merged. Thanks for improving Ignition Transport!

Internal Developers

This section is targeted mostly for 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.

  1. Run the style checker on your personal computer.
  2. Run all tests on your personal computer.
  3. Run your branch through a jenkins trusty build.
  4. Run your branch through a jenkins homebrew build.
  5. Run your branch through a jenkins windows7 build.
  6. Submit the pull request, and include the following:
  1. Link to a passing trusty build.
  2. Link to a passing homebrew build.
  3. Link to a passing windows7 build.
  1. A set of jenkins jobs will run automatically once the pull request is created. Reviewers can reference these automatic jobs and the jenkins jobs listed in your pull request.

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 variable 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 protobuf variable names.
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

Reduce Code Duplication

Check to make sure someone else is not currently working on the same feature, before embarking on a project to add something to Ignition Transport. Check the issue tracker looking for issues with similar ideas.

Write Tests

All code should have a corresponding unit test. Ignition Transport uses GTest for unit testing.

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.

Ignition Transport has a build target called make coverage that will produce a code coverage report. You’ll need lcov installed.

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

Debugging Ignition Transport

Meaningful backtraces

In order to provide meaningful backtraces when using a debugger, such as GDB, Ignition Transport 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 Ignition Transport 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 libignition-transport1-dbg package or compiling Ignition Transport 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 (no -dbg package present) or compiling Ignition Transport 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.

Code Check

Code pushed into the repository should pass a few simple tests. It is also helpful if patches submitted through bitbucket pass these tests. Passing these tests is defined as generating no error or warning messages for each of the following tests.

Static Code Check

Static code checking analyzes your code for bugs, such as potential memory leaks, and style. The Ignition Transport 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 Ignition Transport 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