Contributing

Given our limited resources, we may not review PRs that fail to adhere to this document.

Note that we have a code of conduct, follow it in all your interactions with the project.

You can ignore sections marked as "Under Construction".

How to Contribute

You can contribute to this repository in one of the following ways:

For Trivial Changes
If you believe your change is minor (e.g., typo fixes, small improvements), feel free to make the change directly and submit a pull request (PR).
For Uncertain Changes
If you're unsure whether your proposed change aligns with the project's goals, we encourage you to discuss it first by opening an issue or starting a discussion. This helps ensure alignment and reduces potential rework.
For Exploratory Contributions
If you're unsure but find it easier to share code, you can create a draft PR with the prefix RFC: in the title (e.g., RFC: build: add new feature X). This signals that the PR is a "Request for Comments" and invites feedback from the maintainers and community.

Coding Style

Consistency is key to maintaining a clean and readable codebase. As stated in the LLVM Coding Standards:

If you are extending, enhancing, or bug fixing already implemented code, use the style that is already being used so that the source is uniform and easy to follow.

Please follow this principle to ensure the code remains cohesive and easy to navigate.

Naming Conventions (*Under Construction)

The project's naming conventions are specified in the .clang-tidy file. Here's a brief summary:

Files/Directories: PascalCase
Types/Classes: PascalCase
Variables: snake_case
Class (non-struct) Member Variables: snake_case_
Functions: camelCase
Class (non-struct) Methods: camelCase_

(Note: Variables use snake_case since they tend to be shorter than functions.)

Be mindful of when to use structs vs. classes. For guidance, refer to the Google C++ Style Guide: Structs vs. Classes.

Formatting and Linting

Before submitting a PR, ensure your code adheres to the project's coding standards by running the following tools:

Run the linter (cpplint)
```
cabin lint
```
Run the formatter (clang-format)
```
cabin fmt
```
Run the static analyzer (clang-tidy)
```
cabin tidy  # or make tidy
```

Testing

Always validate your changes to ensure they do not introduce regressions or break existing functionality:

# Unit tests
cabin test  # or make test

# Integration tests
wget https://raw.githubusercontent.com/felipec/sharness/refs/tags/v1.2.1/sharness.sh
wget https://raw.githubusercontent.com/felipec/sharness/refs/tags/v1.2.1/lib-sharness/functions.sh
mv sharness.sh tests/
mkdir tests/lib-sharness
mv functions.sh tests/lib-sharness/
prove -j$(nproc) --shuffle tests/[0-9]*.sh

Make sure to add new tests for any new functionality you introduce. See https://github.com/felipec/sharness/blob/v1.2.1/API.md for more information on how to use sharness.

Documentation

If your changes affect the project's documentation, ensure you update the relevant files in the docs/ directory. You can preview your changes by running the following command:

pip install mkdocs
mkdocs serve

This will start a local server at https://127.0.0.1:8000/.

Make sure to update the table of contents in the mkdocs.yml file to reflect your changes. Also, ensure that the documentation is clear, concise, and formatted correctly.

Before committing anything, ensure that the documentation builds without errors by running:

mkdocs build --strict

Commit Message

Follow Conventional Commits.

Pull Request Style

CI: Verify that all CI checks pass on your fork before submitting the PR. Avoid relying on the CI of this repository to catch errors, as this can cause delays or stalls for other contributors.
Commits: There is no need to squash / force push commits within the PR unless explicitly requested. Keeping separate commits can help reviewers understand the progression of changes.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!