Skip to content

Contribution guidelines

Thank you for investing your time and considering contributing to Retis! :tada:

This guide documents the process to get changes merged into this project, what one should expect, as well as prerequisites for pull-requests and patches to be considered acceptable.

Table of contents

Reporting bugs

Following the guidelines will help the community understand bug reports, which in turns will help in reproducing, triaging and fixing those bugs.

Before submitting the report

  1. Check for similar opened or closed issues. If a similar issue is still opened, please add a comment there.
  2. Check the version used when the bug was triggered. If it was not the latest, please reproduce with it.

Submitting a good bug report

  1. Use a clear, concise and descriptive title.
  2. Describe how to reproduce the bug, in clear exact steps, with examples. The community should not have to guess extra steps, configuration, prerequisites and spend lot of time gathering this information to work on fixing a bug.
  3. How reliable are those steps to reproduce the issue?
  4. Describe the outcome of those steps.
  5. Then describe what would have been expected and why.
  6. If it is performances related, include numbers.

Following-up on the report

  • It's OK to ping once or twice.
  • But give time to the community to reproduce and come up with a solution.
  • Also note we all have limited time and prioritize things.

Suggesting new features

Features requirement vary depending on users, use cases, priorities, etc. But expressing an interest is valuable as it can help prioritizing things and shaping the actual behavior.

Before suggesting a new feature

  1. Check the feature isn't already available. See the tool help.
  2. Check it is not already being planned by looking at the different milestones and issues. If a matching issue is found, please comment on it to express an interest and make suggestions.

Adding an issue to request a new feature

  1. Use a clear, concise and descriptive title.
  2. Describe the environment on which the feature would be used and provide value.
  3. Provide a detailed explanation of what you'd like to be implemented, the expected output and behavior.
  4. If applicable, explain what the current behavior is lacking and how different you'd like it to be.
  5. Understand we have limited time and do prioritize things. In this regard, external contributions for new features are highly recommended and can have a great impact in choosing the direction of the project.

Code contribution

Looking for topics to work on? Please have a look at issues triaged as good first issues and/or help wanted.

Guidelines

  1. Follow the coding style.
  2. Document functions, structures (including members), enums, ..., and the code itself. You can look at the existing code for understanding what level of documentation we expect.
  3. Add unit tests.
  4. Base new work on top of the main branch.

Coding style

We strictly follow the Rust coding style as enforced by rustfmt and have a strong preference for the Linux kernel and particularly its networking flavor coding style for the BPF parts.

Opening a pull-request

  1. Before opening the pull-request, test the changes. Yes, even for those simple one-liner last minute changes.
  2. Check the following commands do not return an error:
  3. cargo fmt --check
  4. cargo clippy -- -D warnings
  5. cargo test, or to include runtime tests, CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER='sudo' cargo test --features=test_cap_bpf
  6. Make sure commits are signed off.
  7. Use a clear, concise and descriptive title.
  8. If the pull-request is linked to an issue, or based on top of another pull-request; reference those.
  9. Describe the environment on which the feature is used and provide value.
  10. Provide a detailed explanation of why the feature was added, how it was done and what is the expected output and behavior.
  11. If applicable, provide a step-by-step guide on how to test the feature.
  12. For pull-requests demonstrating a change to start a discussion, please add "[RFC]" in the pull-request title. Once in a state ready to be formally reviewed for inclusion, remove it.

Following-up on the pull-request

  1. As new versions of the pull-request are pushed, make sure to mark applicable conversations as resolved.
  2. If the pull-request has a conflict and cannot be merged, please rebase on the latest main. This can happen at any time, e.g. when other pull-requests are being merged.