Contributing Guide¶

We love contributions! To make contributing simple for both sides, please:

• Open an issue and describe how you would like to contribute and discuss details with us.
• Create a branch from the develop branch and do the changes:
  • Make sure to follow specifics in our Coding Style.
  • Make sure to use Code Formatter, otherwise the PR check will fail and cannot be merged.
  • Make sure the branch passes Tests against model -- otherwise, the PR check will fail.
  • Make sure to run Static Analysis.
  • Make sure your Commit Messages follow our guidelines.
• Create pull request.

Coding Style¶

Structures and Enums¶

In the public API (include/), we define structured types and enumerations using typedef. We do NOT omit structure (enum) name, to keep possibility to declare using struct/enum keywords. Example:

typedef struct my_struct {
    ...
} my_struct;

typedef enum my_enum {
    ...
} my_enum;

Anywhere else, we do not use typedefs.

Code Formatter¶

We use the clang-format tool for code formatting. Its installation varies dependening on the linux distribution.

To check if clang-format is available on your machine, run:

clang-format --version

We use clang-format to check code format on pushes and PRs into the master and develop branches - this is implemented in the action .github/clang_format_check.yml. It only checks the format and does not fix it - that is the contributor's responsibility.

How to Use It¶

There are multiple ways to format the code using clang-format:

1. For each file with wrong formatting, run:

   clang-format -i <path_to_the_file_to_format>
   

2. If you are using VSCode and the cpptools extension, you can create .vscode/settings.json with the following contents (if it does not already exist):

   { // Add this bracket only if your settings.json file is empty
       "[c]": {
           "editor.defaultFormatter": "ms-vscode.cpptools",
           "editor.formatOnSave": true
       },
       "C_Cpp.formatting": "clangFormat"
   } // Add this bracket only if your settings.json file is empty
   

   This will format the file on each save.
3. There is also the git-clang-format tool, which integrates clang-format with git, but we have not used that yet.
4. Possibly other ways...

Static Analysis¶

To run static analysis, follow these steps:

1. Choose a static analysis tool (e.g., cppcheck, clang-tidy).
2. Configure the tool to analyze the library code.
3. Run the analysis and review the reported issues.

Commit Messages¶

Our commit message format is inspired by Conventional Commits guidelines.

The commit messages should fulfill the following:

< type >[ optional scope ]: < description >
[ optional JIRA REF ]
[ optional body ]
[ optional footer ( s ) ]

Where the meaning of individual fields is:

<type> - Type of commit. Can be one of following:
    - feat     - A new feature.
    - build    - A change to build or compile scripts.
    - ci       - A change to continuous integration setup and scripting.
    - doc      - A change to documentation.
    - refactor - A refactoring of code. Shall not change functionality.
    - test     - A change in tests or test-bench environment.
    - fix       - Fix of incorrect functionality.
    - perf     - Performance enhancement.
    - deps     - A change to dependency settings

<description>  - Part of the repository or flow where the change is made. The first line of the commit message shall be at most 72 characters long.

scope          - Optional part of the repository or flow where the change is made.

JIRA REF       - Optional reference to a JIRA issue

body           - Optional arbitrary number of paragraphs describing what the commit does.

footer         - Optional footer (see https://www.conventionalcommits.org/en/v1.0.0/#specification)