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.
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¶
- 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.
- 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
issue_ followed by the issue number. E.g.:
- Write your code.
This is the fun part.
- Write tests.
A pull request will only be accepted if it has tests. See the Test coverage section below for more information.
- Compiler warnings.
Code must have zero compile warnings. This currently only applies to Linux.
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:
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 testin your build directory.
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 bad.
- Small pull requests.
Submit a pull request when you ready.
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 Ignition Transport!
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.
- Run the style checker on your personal computer.
- Run all tests on your personal computer.
- Run your branch through a jenkins trusty build.
- Run your branch through a jenkins homebrew build.
- Run your branch through a jenkins windows7 build.
- Submit the pull request, and include the following:
- 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.
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
forloops. 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
&next to the variable name, not next to the type. For example:
int &variableis good, but
int& variableis 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.
All code should have a corresponding unit test. Ignition Transport uses GTest for unit testing.
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.
- In your
buildfolder, compile Ignition Transport with
cmake -DCMAKE_BUILD_TYPE=Coverage ..\ make
- Run a single test, or all the tests:
- Make the coverage report:
- View the coverage report:
Debugging Ignition Transport¶
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
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-dbgpackage or compiling Ignition Transport from source using the
CMAKE_BUILD_TYPEmode (which is the default if no mode is provided). This will set up
-O2optimization 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
-dbgpackage present) or compiling Ignition Transport from source using the
CMAKE_BUILD_TYPEoption. 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 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:
It takes a few minutes to run. Fix all errors and warnings until the output looks like:
Total errors found: 0