Skip to main content
Thank you for investing your time and considering contributing to Retis! This guide documents the process to get changes merged into the project and what to expect when contributing.

​
Reporting Bugs

Following these guidelines will help the community understand, reproduce, and fix bugs effectively.

​
Before Submitting a Report

Check for Similar Issues

Search for similar open or closed issues. If found, add a comment to the existing issue.

Verify Version

Check if you’re using the latest version. If not, reproduce the bug with the latest release.

​
Submitting a Good Bug Report

A well-structured bug report should include:
  1. Clear Title - Use a concise and descriptive title
  2. Version Information - Include the output of retis --version
  3. Reproduction Steps - Provide exact, clear steps to reproduce the bug
  4. Reliability - How consistently can the bug be reproduced?
  5. Actual Outcome - Describe what actually happens
  6. Expected Outcome - Describe what should happen and why
  7. Performance Data - Include numbers if the issue is performance-related
The community should not have to guess extra steps, configuration, or prerequisites. Provide complete information upfront.

​
Following Up

  • It’s OK to ping once or twice
  • Give the community time to reproduce and develop a solution
  • Remember that everyone has limited time and must prioritize

​
Suggesting New Features

Feature requests help shape the direction of the project and prioritize development efforts.

​
Before Suggesting a Feature

  1. Check Existing Features - Review the tool’s help documentation
  2. Search Issues and Milestones - Look at milestones and issues
  3. Comment on Existing Issues - If found, express interest and add suggestions

​
Creating a Feature Request

  1. Use a clear, concise and descriptive title
  2. Describe the environment and use case
  3. Provide detailed explanation of the desired implementation
  4. Explain how current behavior is lacking
  5. Understand that external contributions are highly valued
External contributions for new features have a great impact on choosing the direction of the project.

​
Code Contributions

​
Development Guidelines

Follow Coding Style

Adhere to Rust and BPF coding standards

Document Your Code

Document functions, structures, enums, and complex logic

Add Unit Tests

Include tests for new functionality

Use Conscious Language

Choose inclusive terminology in your code

​
Development Setup

Base your work on the main branch: 
git clone https://github.com/retis-org/retis.git
cd retis
git checkout main

​
Coding Style

Rust Code - Strictly follow the Rust coding style as enforced by rustfmt BPF Code - Follow the Linux kernel coding style as enforced by checkpatch.pl, particularly the networking flavor for multi-line comments.
checkpatch.pl can generate false positives. When this happens, the coding style rules take precedence.

​
Events and Rust Bindings

When introducing new events or modifying existing ones:
  1. Annotate - Add __binding annotation to new event types
  2. Generate - Run make gen-bindings
  3. Commit - Include generated files in your pull request
Submit binding changes in separate patches to facilitate review. You’ll need bindgen installed - check the current version in bindings headers.
Requirements for binding generation: 
# Install bindgen
cargo install bindgen-cli@<VERSION>

# Install Python bindings for Clang (Fedora example)
dnf -y install python3-clang

​
Testing Guidelines

Before opening a pull request: 
# Check format and lint issues
make lints

# Run unit tests
make test V=1

# Run functional tests (requires sudo)
sudo make functional-tests

# Run Python tests
make pytest V=1

​
Code Coverage

Assess test coverage locally: 
# Install tools
cargo install cargo-llvm-cov
rustup component add llvm-tools-preview

# Generate coverage
make test COV=1

# Generate HTML report
CARGO_CMD_OPTS=--html make report-cov
If your default toolchain isn’t installed via rustup, set CARGO_OPTS=+nightly to specify a rustup-installed toolchain.

​
Backward Compatibility

Retis maintains compatibility guarantees as described in the compatibility documentation.
  • Ensure backward compatibility of generated events
  • Update retis-events/src/compat/compat.rs when needed
  • Test with previous versions when applicable

​
Pull Request Process

​
Before Opening a PR

Test Your Changes

Test even simple one-liner changes

Run Lints

Execute make lints and fix issues

Sign Off Commits

Follow DCO requirements

Clear Description

Use descriptive title and detailed explanation

​
PR Description Checklist

  1. Clear Title - Concise and descriptive
  2. References - Link related issues or PRs
  3. Environment - Describe where the feature provides value
  4. Explanation - Detail why, how, and expected behavior
  5. Testing Steps - Provide step-by-step testing guide
  6. RFC Tag - Add “[RFC]” prefix for discussion-focused PRs

​
Following Up

  1. Resolve Conversations - Mark applicable discussions as resolved
  2. Handle Conflicts - Rebase on latest main if needed
  3. Be Patient - The community has limited time and prioritizes accordingly

​
Python Bindings Development

Quick build and test workflow using maturin: 
# Create virtual environment
python -m venv venv && source venv/bin/activate

# Install maturin
pip install maturin

# Build and install bindings
maturin develop -m retis-events/Cargo.toml -F python-lib

# Test
python
>>> import retis

​
Documentation Preview

Generate a local preview of the documentation: 
# Install requirements
pip install -r docs/requirements.txt

# Serve documentation
mkdocs serve
Then navigate to localhost:8000 in your browser.

​
Getting Help

GitHub Issues

Ask questions and report problems

Discussions

Join community discussions
Your contributions help make Retis better for everyone. Thank you for being part of the community!

Build docs developers (and LLMs) love

Get started for freeTalk to us