Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
258 lines (183 loc) · 7.68 KB

CONTRIBUTING.md

File metadata and controls

258 lines (183 loc) · 7.68 KB
Raw

Contributing

  • Thank you for your interest in contributing to the Communication Module of the Eclipse SCORE project!
  • This guide will walk you through the necessary steps to get started with development, adhere to our standards, and successfully submit your contributions.

Eclipse Contributor Agreement (ECA)

Before making any contributions, you must sign the Eclipse Contributor Agreement (ECA). This is a mandatory requirement for all contributors to Eclipse projects.

Sign the ECA here: https://www.eclipse.org/legal/ECA.php

Pull requests from contributors who have not signed the ECA will not be accepted.

Contribution Workflow

To ensure a smooth contribution process, please follow the steps below:

  1. Fork the repository to your GitHub account.
  2. Create a feature branch from your fork: 
    git checkout -b feature/your-feature-name
  3. Write clean and modular code, adhering to:
    • C++17 standard
    • Google C++ Style Guide
  4. Add tests for any new functionality.
  5. Ensure all tests pass before submitting: 
    bazel test //...
  6. Open a Pull Request from your feature branch to the main branch of the upstream repository.
    • Provide a clear title and description of your changes.
    • Reference any related issues.

Development Setup

General Prerequisites

OS-specific Prerequisites

We strive to be independent of the host platform via bazel sandboxing. Some host platforms come with limitations that bazel cannot sandbox sufficiently. For these platforms we collect instructions below.

Please be aware, that while we officially support Ubuntu 24.04 as the host platform that we also test in our CI. While other platforms generally should work, we can give no such guarantee. Should you face issues with your host platform, feel free to raise an issue or discussion where we will try to support.

Ubuntu 24.04 and newer

Starting with Ubuntu 24.04 the security framework apparmor was introduced. The standard configuration of apparmor prohibits unprivileged user namespaces. This interferes with the bazel sandboxing mechanism and inhibits the linux-sandbox. Bazel falls back to a less powerful sandboxing mechanism that is insufficient for our project. This affects many bazel tests and potentially any bazel runnables.

To work around this issue, you can run a bash script, which you can get by cloning the cicd-actions repository

git clone --depth=1 https://github.com/eclipse-score/cicd-actions

after which you can run

bash <path to cicd-actions repository>/unblock_user_namespace_for_linux_sandbox/action_callable.sh

Note. To take this into effect force, a bazel restart by shutting it down 1st

bazel shutdown

These steps must be rerun whenever the bazel version is updated.

Build Instructions

To build and test the Communication Module, follow the steps below from the project root:

# Build all targets
bazel build //...

# Run all tests
bazel test //...

Optional: Configure a local Ubuntu snapshot mirror

The Ubuntu snapshot mirrors are sometimes unreliable. See: https://answers.launchpad.net/launchpad/+question/824541

If you have access to a more reliable Ubuntu snapshot mirror, you can make Bazel try it first while keeping the public snapshot.ubuntu.com URL as fallback.

An example for such a snapshot mirror service is https://stablebuild.com

  1. Create a local downloader config at user.downloader_config (this file is ignored by git). Replace the <private-mirror-tag> with the tag provided by the StableBuild API
rewrite snapshot.ubuntu.com/ubuntu/[^/]*/(.*) <private-mirror-tag>.debmirror.stablebuild.com/2026-04-01T10:40:01Z/archive.ubuntu.com/ubuntu/$1
rewrite snapshot.ubuntu.com/ubuntu/[^/]*/(.*) <private-mirror-tag>.debmirror.stablebuild.com/2026-04-01T10:40:01Z/ports.ubuntu.com/$1
rewrite snapshot.ubuntu.com/ubuntu/(.*) snapshot.ubuntu.com/ubuntu/$1
  1. Point Bazel to this local config in user.bazelrc (also ignored by git):
common --downloader_config=user.downloader_config
  1. Restart the Bazel server to reload the downloader config
bazel shutdown

Linting Instructions

For Linting the Code following solutions are available:

Copyright Checker:

# Check Sources
bazel run //:copyright.check

# Fix Sources
bazel run //:copyright.fix

C++ and Bazel files formatter:

# Check Sources
bazel run //:format.check

# Fix Sources
bazel run //:format

Testing Instructions

The Communication Module includes extensive tests. Use the following commands:

Run All Tests

bazel test //...

Run Specific Test Suites

bazel test //score/mw/com/impl:all
bazel test //score/mw/com/message_passing:all

Test Categories

  • Unit Tests: Component-level testing
  • Integration Tests: Cross-component interactions
  • Performance Tests: Latency and throughput benchmarks
  • Safety Tests: ASIL-B compliance verification

Additional Resources

For project details, documentation, and support resources, please refer to the main README.md. For the release process, see RELEASING.md.

How to Document

This section explains how to document C++ code so it appears in the generated API documentation.

API documentation is generated using Doxygen and integrated via Breathe. Due to Sphinx version < 9.x limitations with complex C++ templates, use specific class and function directives rather than namespace-level documentation.

Automatic API Documentation with @api Tag

The project includes an automated RST generation utility that extracts items tagged with @api in Doxygen comments and generates categorized documentation.

Add the @api tag to any Doxygen comment block to include it in the generated API documentation:

/**
 * @brief Connection handler for client communication
 * @api
 */
class ClientConnection {
    // ...
};

/**
 * @brief Initialize the communication system
 * @return true if successful
 * @api
 */
bool initialize();

The utility automatically creates:

  • API Index — overview of all tagged items
  • Namespace Reference — namespaces containing @api items
  • Class Reference — classes and structs with @api tag
  • Member Reference — functions and methods with @api tag

Build integration:

generate_api_rst(
    name = "generate_api_rst",
    doxygen_xml = "//path/to:doxygen_target",
    output_dir = "generated",
    project_name = "mw::com",
)

The generated RST files are automatically included in the Sphinx documentation under the "Generated API Documentation" section.

Using Breathe Directives

To document specific classes or functions, use these Breathe directives in RST files:

Document a specific class:

.. doxygenclass:: score::message_passing::detail::ClientConnection
    :members:
    :protected-members:
    :undoc-members:

Document a specific function:

.. doxygenfunction:: score::mw::com::functionName

Document a struct:

.. doxygenstruct:: score::mw::com::ConfigStruct
    :members:

Further Resources

  • Browse the Doxygen-generated HTML at bazel-bin/score/mw/com/design/doxygen_build/html/index.html
  • Review header files in score/mw/com/ for inline documentation
  • Check the design documentation at score/mw/com/design/

Thank you for contributing to the Eclipse SCORE Communication Module!