Contributing to SOME/IP Stack

Thank you for your interest in contributing to the SOME/IP Stack! This document provides guidelines and information for contributors.

Code of Conduct
Getting Started
Development Workflow
Coding Standards
Testing
- Running Tests Locally (Pre-PR)
Documentation
Pull Request Process
Reporting Issues

Code of Conduct

This project follows a code of conduct to ensure a welcoming environment for all contributors. By participating, you agree to:

Be respectful and inclusive
Focus on constructive feedback
Accept responsibility for mistakes
Show empathy towards other contributors
Help create a positive community

Getting Started

Prerequisites

C++17 compatible compiler (GCC 9+, Clang 10+, MSVC 2019+)
CMake 3.20+
Git
(Optional) Doxygen for documentation generation

Development Setup

Fork and Clone

git clone https://github.com/your-username/someip-stack.git
cd someip-stack

Build Dependencies
```
./scripts/setup_deps.sh
```

Build Project

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
make -j$(nproc)

Run Tests
```
ctest --output-on-failure
```

Development Workflow

Branch Naming

feature/description: New features
bugfix/description: Bug fixes
refactor/description: Code refactoring
docs/description: Documentation updates
test/description: Test additions/updates

Commit Messages

We enforce Conventional Commits format using pre-commit hooks and CI validation. All commits in PRs must follow this format or the pipeline will fail.

<type>(<optional scope>): <description>

[optional body]

[optional footer]

Types:

feat: New features
fix: Bug fixes
docs: Documentation changes
style: Code style changes (formatting, no logic change)
refactor: Code refactoring (no feature/fix)
perf: Performance improvements
test: Adding or updating tests
build: Build system or dependencies
ci: CI/CD configuration
chore: Maintenance tasks
revert: Reverting previous commits

Examples:

feat(transport): add TCP transport binding

fix(serialization): handle endianness correctly on ARM

test(message): add comprehensive message validation tests

docs: update README with build instructions

chore: update dependencies

Pre-commit Hooks Setup

We use pre-commit to enforce code quality and commit message format locally:

# Install pre-commit
pip install pre-commit

# Install hooks (one-time setup)
pre-commit install
pre-commit install --hook-type commit-msg

# Run manually on all files
pre-commit run --all-files

What the hooks check:

Trailing whitespace and end-of-file issues
Valid YAML and JSON files
No large files added (>500KB)
No merge conflicts or private keys
Consistent line endings (LF)
Commit message follows Conventional Commits format

Note: The CI pipeline will run these same checks on all PRs. Setting up pre-commit locally helps catch issues before pushing.

Coding Standards

C++ Standards

Language: C++17
Standard Library: Use modern C++ features appropriately
Headers: Include what you use, prefer forward declarations

Naming Conventions

Classes: PascalCase (e.g., Message, UdpTransport)
Functions/Methods: camelCase (e.g., serialize(), sendMessage())
Variables: snake_case (e.g., message_id, local_endpoint)
Constants: SCREAMING_SNAKE_CASE (e.g., HEADER_SIZE)
Namespaces: lowercase (e.g., someip, transport)

Code Style

Indentation: 4 spaces (no tabs)
Line Length: 100 characters maximum
Braces: Stroustrup style (opening brace on same line)
Includes: Group by type, separate with blank lines
- System headers first (<iostream>, <vector>)
- Project headers second ("someip/message.h")
- Local headers last ("transport/udp_transport.h")

Safety-Oriented Guidelines (non-certified)

Since safety alignment is a goal (not certified):

RAII: Use Resource Acquisition Is Initialization
No Raw Pointers: Use smart pointers for ownership
Const Correctness: Use const appropriately
Error Handling: Return error codes, no exceptions in core logic
Thread Safety: Document thread safety guarantees
Input Validation: Validate all external inputs

Example Code Style

#include <memory>
#include <vector>

#include "someip/message.h"
#include "transport/endpoint.h"

namespace someip {
namespace transport {

class UdpTransport : public ITransport {
public:
    explicit UdpTransport(const Endpoint& local_endpoint);
    ~UdpTransport();

    Result initialize() override;
    Result send_message(const Message& message,
                       const Endpoint& destination) override;

private:
    Endpoint local_endpoint_;
    int socket_fd_;
    std::vector<uint8_t> receive_buffer_;
};

}  // namespace transport
}  // namespace someip

Testing

Test Categories

Unit Tests: Individual component testing
Integration Tests: Component interaction testing
System Tests: End-to-end functionality testing
Performance Tests: Benchmarking and profiling

Test Naming

Files: test_component.cpp (e.g., test_message.cpp)
Test Cases: TestSuite.TestCase (e.g., MessageTest.Constructor)
Test Names: Descriptive and specific

Test Coverage

Target: >90% line coverage for critical components
Tools: gcov, lcov for coverage reporting
Safety-Critical: 100% branch coverage for safety functions

Writing Tests

#include <gtest/gtest.h>
#include "someip/message.h"

class MessageTest : public ::testing::Test {
protected:
    void SetUp() override {
        // Test setup
    }

    void TearDown() override {
        // Test cleanup
    }
};

TEST_F(MessageTest, Constructor) {
    MessageId msg_id(0x1000, 0x0001);
    Message msg(msg_id, RequestId(0x1234, 0x5678));

    EXPECT_EQ(msg.get_service_id(), 0x1000);
    EXPECT_EQ(msg.get_method_id(), 0x0001);
}

TEST_F(MessageTest, SerializationRoundTrip) {
    // Test serialization and deserialization
    Message original(MessageId(0x1000, 0x0001), RequestId(0x1234, 0x5678));
    std::vector<uint8_t> data = original.serialize();

    Message deserialized;
    ASSERT_TRUE(deserialized.deserialize(data));

    EXPECT_EQ(deserialized.get_service_id(), original.get_service_id());
    EXPECT_EQ(deserialized.get_method_id(), original.get_method_id());
}

Running Tests Locally (Pre-PR)

Before opening a pull request you must run the pre-PR test suite and ensure every check passes. The script mirrors the CI pipeline so a green local run reliably predicts green CI.

# macOS / Ubuntu / Fedora
./scripts/run_pre_pr_tests.sh

# Windows (PowerShell)
.\scripts\run_pre_pr_tests.ps1

The script runs, in order:

Pre-commit hooks (pre-commit run --all-files)
C++ build via the appropriate CMake preset for your OS
C++ unit tests via CTest (GTest)
Python integration & system tests via pytest

Optional flags (both scripts):

Flag	Description
`--sanitizers` / `-Sanitizers`	Rebuild with ASan + UBSan and re-run CTest
`--coverage` / `-Coverage`	Rebuild with gcov flags, run tests, generate report
`--all` / `-All`	Enable both sanitizers and coverage
`--skip-python` / `-SkipPython`	Skip Python integration / system tests
`--help` / `-Help`	Show usage information

Platform Prerequisites

macOS

# Xcode Command Line Tools (provides clang/clang++)
xcode-select --install

# CMake, Python, pre-commit
brew install cmake python
pip install pre-commit
pre-commit install && pre-commit install --hook-type commit-msg

# (Optional) Ninja for faster builds
brew install ninja

CMake preset: host-macos-tests. The script auto-detects macOS and selects this preset. Note: nproc is unavailable — the script uses sysctl -n hw.ncpu automatically.

Ubuntu (22.04 / 24.04)

sudo apt-get update
sudo apt-get install -y build-essential cmake python3 python3-pip python3-venv

pip install pre-commit
pre-commit install && pre-commit install --hook-type commit-msg

CMake preset: host-linux-tests. CI tests with both GCC and Clang — to test with Clang locally:

cmake --preset host-linux-tests \
  -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++

Fedora (42+)

sudo dnf install -y gcc gcc-c++ clang cmake ninja-build python3 python3-pip

pip install pre-commit
pre-commit install && pre-commit install --hook-type commit-msg

CMake preset: host-linux-tests. CI runs inside a fedora:42 container — to replicate locally with Podman/Docker:

podman run --rm -v "$PWD:/src:Z" -w /src fedora:42 \
  bash -c "dnf install -y gcc gcc-c++ cmake ninja-build python3 python3-pip && \
           pip install pre-commit && ./scripts/run_pre_pr_tests.sh"

Windows

Visual Studio 2019+ with the Desktop development with C++ workload (provides MSVC cl)
CMake (bundled with Visual Studio or install standalone)
Python 3.12+ (python.org)

pip install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg

CMake preset: host-windows-tests. The PowerShell script auto-detects Windows. Note: PAL mock conformance tests are excluded on Windows (they depend on POSIX headers).

Running Individual Tests

# Run a specific CTest target
ctest --test-dir build/<preset> -R MessageTest

# Run with coverage (manual)
cmake -B build/coverage -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_FLAGS="--coverage" -DBUILD_TESTS=ON
cmake --build build/coverage
ctest --test-dir build/coverage

Documentation

Documentation Standards

Format: Markdown for guides, Doxygen for API docs
Location: docs/ for guides, code comments for API docs
Completeness: Document all public APIs
Examples: Provide usage examples

Doxygen Comments

/**
 * @brief Sends a message to the specified endpoint
 *
 * This method transmits a SOME/IP message to a remote endpoint using
 * the configured transport protocol.
 *
 * @param message The message to send
 * @param destination The destination endpoint
 * @return Result indicating success or failure
 *
 * @thread_safety Thread-safe
 * @safety Safety alignment in progress (not certified)
 */
Result send_message(const Message& message, const Endpoint& destination);

Documentation Updates

Update documentation with code changes
Keep API documentation synchronized
Update examples when interfaces change

Pull Request Process

Before Submitting

Run the pre-PR test suite: Execute ./scripts/run_pre_pr_tests.sh (or .\scripts\run_pre_pr_tests.ps1 on Windows) and ensure all checks pass. See Running Tests Locally for platform-specific setup.
Commit Messages: Ensure all commits follow Conventional Commits format
Code Review: Self-review your code
Tests: Add/update tests for new functionality
Documentation: Update relevant documentation
Linting: Ensure code follows style guidelines

Pull Request Template

## Description
Brief description of the changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Refactoring

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing performed

## Checklist
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] Tests pass
- [ ] No breaking changes

## Additional Notes
Any additional information or context

Review Process

Automated Checks: CI/CD runs:
- Pre-commit hooks (code quality checks)
- Commit message validation (Conventional Commits format)
- Build verification (multiple compilers)
- Test suite execution
Peer Review: At least one maintainer review
Approval: Maintainers approve changes
Merge: Squash merge with descriptive commit message

Important: PRs with invalid commit messages will fail CI and cannot be merged.

Reporting Issues

Bug Reports

When reporting bugs, please include:

Description: Clear description of the issue
Steps to Reproduce: Minimal steps to reproduce
Expected Behavior: What should happen
Actual Behavior: What actually happens
Environment: OS, compiler, versions
Logs: Relevant error messages or logs

Feature Requests

For feature requests, please include:

Description: What feature you want
Use Case: Why you need this feature
Alternatives: Considered alternatives
Implementation Ideas: How you think it should work

Issue Labels

bug: Bug reports
enhancement: Feature requests
documentation: Documentation issues
question: Questions and discussions
help wanted: Good first issues
good first issue: Beginner-friendly issues

Getting Help

Documentation: Check docs/ directory
Issues: Search existing issues on GitHub
Discussions: Use GitHub Discussions for questions
Community: Join our community channels

Thank you for contributing to the SOME/IP Stack! 🚗✨

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to SOME/IP Stack

Table of Contents

Code of Conduct

Getting Started

Prerequisites

Development Setup

Development Workflow

Branch Naming

Commit Messages

Pre-commit Hooks Setup

Coding Standards

C++ Standards

Naming Conventions

Code Style

Safety-Oriented Guidelines (non-certified)

Example Code Style

Testing

Test Categories

Test Naming

Test Coverage

Writing Tests

Running Tests Locally (Pre-PR)

Platform Prerequisites

Running Individual Tests

Documentation

Documentation Standards

Doxygen Comments

Documentation Updates

Pull Request Process

Before Submitting

Pull Request Template

Review Process

Reporting Issues

Bug Reports

Feature Requests

Issue Labels

Getting Help

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to SOME/IP Stack

Table of Contents

Code of Conduct

Getting Started

Prerequisites

Development Setup

Development Workflow

Branch Naming

Commit Messages

Pre-commit Hooks Setup

Coding Standards

C++ Standards

Naming Conventions

Code Style

Safety-Oriented Guidelines (non-certified)

Example Code Style

Testing

Test Categories

Test Naming

Test Coverage

Writing Tests

Running Tests Locally (Pre-PR)

Platform Prerequisites

Running Individual Tests

Documentation

Documentation Standards

Doxygen Comments

Documentation Updates

Pull Request Process

Before Submitting

Pull Request Template

Review Process

Reporting Issues

Bug Reports

Feature Requests

Issue Labels

Getting Help