|
| 1 | +# Contributing to Eclipse iceoryx |
| 2 | + |
| 3 | +Thanks for your interest in this project. |
| 4 | + |
| 5 | +## Project description |
| 6 | + |
| 7 | +In domains like automotive, robotics or gaming, a huge amount of data must be |
| 8 | +transferred between different parts of the system. If these parts are actually |
| 9 | +different processes on a POSIX based operating system like Linux, this huge |
| 10 | +amount of data has to be transferred via an inter-process-communication (IPC) |
| 11 | +mechanism. |
| 12 | + |
| 13 | +* https://projects.eclipse.org/projects/technology.iceoryx |
| 14 | + |
| 15 | +## Developer resources |
| 16 | + |
| 17 | +Information regarding source code management, builds, coding standards, and |
| 18 | +more. |
| 19 | + |
| 20 | +* https://projects.eclipse.org/projects/technology.iceoryx/developer |
| 21 | + |
| 22 | +The project maintains the following source code repositories |
| 23 | + |
| 24 | +* https://github.com/eclipse/iceoryx |
| 25 | + |
| 26 | +## Eclipse Contributor Agreement |
| 27 | + |
| 28 | +Before your contribution can be accepted by the project team contributors must |
| 29 | +electronically sign the Eclipse Contributor Agreement (ECA). |
| 30 | + |
| 31 | +* http://www.eclipse.org/legal/ECA.php |
| 32 | + |
| 33 | +Commits that are provided by non-committers must have a Signed-off-by field in |
| 34 | +the footer indicating that the author is aware of the terms by which the |
| 35 | +contribution has been provided to the project. The non-committer must |
| 36 | +additionally have an Eclipse Foundation account and must have a signed Eclipse |
| 37 | +Contributor Agreement (ECA) on file. |
| 38 | + |
| 39 | +For more information, please see the Eclipse Committer Handbook: |
| 40 | +https://www.eclipse.org/projects/handbook/#resources-commit |
| 41 | + |
| 42 | +## Contact |
| 43 | + |
| 44 | +Contact the project developers via the project's "dev" list. |
| 45 | + |
| 46 | +* iceoryx-dev@eclipse.org |
| 47 | + |
| 48 | +## Feature request and bugs |
| 49 | + |
| 50 | +We love pull requests! The next sections try to cover most of the relevant questions. For larger contributions or |
| 51 | +architectural changes we'd kindly ask you to get in touch with one of the maintainers beforehand. If you would like to |
| 52 | +report a bug or propose a new feature, please raise an issue before raising a pull request. This makes it easier to |
| 53 | +track. Beforehand, please make sure you have: |
| 54 | + |
| 55 | +1. Signed the [ECA](http://www.eclipse.org/legal/ECA.php) |
| 56 | +2. All commits have been commited with `git commit -s` |
| 57 | + |
| 58 | +## Coding style |
| 59 | + |
| 60 | +We love the [C++ core guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines). If in doubt please try |
| 61 | +to follow them as well as our unwritten conventions in the exisiting parts of the code base. |
| 62 | +Please format your code with the provided [clang-format](https://clang.llvm.org/docs/ClangFormat.html) and |
| 63 | +[clang-tidy](https://clang.llvm.org/extra/clang-tidy/) before raising a pull request. Lots of IDEs do read the |
| 64 | +clang-format file these days. |
| 65 | + |
| 66 | +We created some convenient rules to highlite some bits that you might not be used to in other FOSS projects. They are |
| 67 | +helpful to build embedded systems for safety fields like automotive or avionics. It is possible that not the whole |
| 68 | +codebase follows these rules, things are work in progress. |
| 69 | + |
| 70 | +1) **No heap is allowed**, static memory management hugely decreases the complexity of your software (e.g. cxx::vector |
| 71 | + without heap) |
| 72 | +2) **No exception are allowed**, all function and methods need to have `noexcept` in their signature |
| 73 | +3) **No undefined behavior**, zero-cost abstract is not feasible in high safety environments |
| 74 | +4) **Use C++11**, however we try to introduce C++14 as fast as possible |
| 75 | +5) **[Rule of Five](https://en.wikipedia.org/wiki/Rule_of_three_(C%2B%2B_programming))**, if there is a non-default |
| 76 | + destructor needed, the rule of five has to be applied |
| 77 | +6) **[STL](https://en.wikipedia.org/wiki/Standard_Template_Library)**, we aim to be compatible towards the STL, but |
| 78 | + our code may contain additions which are not compatible with the STL (e.g. `iox::cxx::vector::emplace_back()` |
| 79 | + does return a bool) |
| 80 | +7) **Always use `iox::log::Logger`**, instead of `printf()` |
| 81 | +8) **Always use `iox::ErrorHandler()`**, instead of the direct STL calls |
| 82 | +9) **No include guards** Till [modules](https://isocpp.org/files/papers/n4720.pdf) are arriving with C++20, we'll rely |
| 83 | + on `#pragma once` instead of the usual include guards |
| 84 | + |
| 85 | +### Naming conventions |
| 86 | + |
| 87 | +* File names with `lower_snake_case`: `my_thing.hpp` |
| 88 | +* Structs, classes and enum classes in `UpperCamelCase`: `class MyClass{}` |
| 89 | +* Methods and variables in `lowerCamelCase`: `uint16_t myVariable` |
| 90 | +* Compile time constants, also enum values in `UPPER_SNAKE_CASE`: `static constexpr uint16_t MY_CONSTANT` |
| 91 | +* Class members start with `m_`: `m_myMember` |
| 92 | +* Namespaces in `lower_snake_case` : `my_namespace` |
| 93 | + |
| 94 | +### Doxygen |
| 95 | + |
| 96 | +Please use [doxygen](http://www.doxygen.nl/) to document your code. |
| 97 | + |
| 98 | +The following doxygen comments are required for public API headers: |
| 99 | + |
| 100 | + /// @brief short description |
| 101 | + /// @param[in] / [out] / [in,out] name description |
| 102 | + /// @return description |
| 103 | + |
| 104 | +## Folder structure |
| 105 | + |
| 106 | +The folder structure boils down to: |
| 107 | + |
| 108 | +* iceoryx_COMPONENT |
| 109 | + * cmake: All cmakes files go here, needed for `find_pkg()` |
| 110 | + * doc: Manuals and documentation |
| 111 | + * include: public headers with stable API |
| 112 | + * internal: public headers with unstable API, which might change quite frequently |
| 113 | + * source: implementation files |
| 114 | + * test: unit and integrations tests |
| 115 | + * CMakeLists.txt: Build the component separately |
| 116 | +* examples_iceoryx: Examples described in the main [Readme.md](./README.md#user-content-examples) |
| 117 | + |
| 118 | +All new code should follow the folder structure. |
| 119 | + |
| 120 | +## Testing |
| 121 | + |
| 122 | +We use [Google test](https://github.com/google/googletest) for our unit and integration tests. We require compatibility |
| 123 | +with the version 1.8.1. |
| 124 | + |
| 125 | +### Unit tests (aka module tests) |
| 126 | + |
| 127 | +Units tests are black box tests, that test the public interface of a class. They are required for all new code. |
| 128 | + |
| 129 | +### Integration tests |
| 130 | + |
| 131 | +Integration tests are composition of more than one class and test their interaction. They are optional for new code. |
| 132 | + |
| 133 | +## Legal & Compliance |
| 134 | + |
| 135 | +### Dependencies |
| 136 | + |
| 137 | +* [POSIX](https://en.wikipedia.org/wiki/POSIX) |
| 138 | +Iceoryx aims to be fully POSIX-compliant towards the current revision POSIX.1-2017 (IEEE 1003.1-2017). Please write |
| 139 | +your code as portable as possible. Currently our focus is [QNX](https://blackberry.qnx.com/en) and Linux. |
| 140 | + |
| 141 | +* [ACL](https://en.wikipedia.org/wiki/Access-control_list) |
| 142 | + |
| 143 | +* [ncurses](https://www.gnu.org/software/ncurses/) |
| 144 | + |
| 145 | +### Safety |
| 146 | + |
| 147 | +We aim for [ASIL-D](https://en.wikipedia.org/wiki/Automotive_Safety_Integrity_Level#ASIL_D) compliance. The |
| 148 | +[ISO262](https://en.wikipedia.org/wiki/ISO_26262) is also a good read-up if you want to learn more about automotive |
| 149 | +safety. As of now we don't have any continous integration checks implemented but will rely on reviews during the pull |
| 150 | +requests. |
| 151 | + |
| 152 | +### Security |
| 153 | + |
| 154 | +A good read-up on security topics with C++ is the |
| 155 | +[SEI CERT C++ Coding Standard](https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=88046682). If you are |
| 156 | +unsure you can always read-up there and use it as best practise. It is possible that not the whole codebase follows |
| 157 | +these rules, things are work in progress. But this is where we want go. As of now we don't have any continous |
| 158 | +integration checks implemented but will rely on reviews during the pull requests. |
| 159 | + |
| 160 | +### Header |
| 161 | + |
| 162 | +Each source file needs to have this header: |
| 163 | + |
| 164 | + // Copyright (c) [year] by [Name of author]. All rights reserved. |
| 165 | + // |
| 166 | + // Licensed under the Apache License, Version 2.0 (the "License"); |
| 167 | + // you may not use this file except in compliance with the License. |
| 168 | + // You may obtain a copy of the License at |
| 169 | + // |
| 170 | + // http://www.apache.org/licenses/LICENSE-2.0 |
| 171 | + // |
| 172 | + // Unless required by applicable law or agreed to in writing, software |
| 173 | + // distributed under the License is distributed on an "AS IS" BASIS, |
| 174 | + // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 175 | + // See the License for the specific language governing permissions and |
| 176 | + // limitations under the License. |
0 commit comments