Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
171 lines (127 loc) · 4.34 KB

CONTRIBUTING.md

File metadata and controls

171 lines (127 loc) · 4.34 KB
Raw

Contribute to Cubic

Contributions are very welcome. Thank you for taking the time to contribute to Cubic!

How to contribute?

There are many ways to contribute, no matter your background:

  • Report bugs — open an issue on GitHub if something does not work as expected.
  • Request features — open an issue on GitHub to suggest improvements.
  • Improve documentation — fix typos, clarify explanations, or add missing guides in the docs/ directory.
  • Submit code changes — open a pull request with your fix or feature.
  • Join the discussion — share feedback and ideas on existing issues and pull requests.

How to set up a development environment?

Before building Cubic, ensure you have the necessary tools installed:

  • Git
  • GCC
  • Rustup

For Debian, Ubuntu, and derivatives:

sudo apt update && sudo apt install -y git gcc rustup

For Fedora and derivatives:

sudo dnf install -y git gcc rustup && sudo rustup-init -y

For OpenSUSE and derivatives:

sudo zypper install -y git gcc rustup

Then clone the repository:

git clone https://github.com/cubic-vm/cubic.git
cd cubic/
rustup toolchain install stable

How to build?

Debug build (fast compile, no optimisations):

cargo build

Release build (optimised, matches the distributed binary):

cargo build --locked --release

The release binary is written to target/release/cubic.

Note: --locked ensures the build uses the exact dependency versions intended by the developers.

How to run the binary?

cargo run -- [COMMAND] [OPTIONS]

For example:

cargo run -- images
cargo run -- --help

Runtime dependencies

To actually run virtual machines, Cubic requires QEMU to be installed on the host:

  • qemu-system-x86_64
  • qemu-system-aarch64
  • qemu-img

How to test?

cargo test

To run a single test by name:

cargo test <test_name>

How to generate the documentation?

The documentation is built with Sphinx. The source files live in the docs/ directory and are written in reStructuredText.

First, generate the CLI reference pages from the binary's help output:

./scripts/generate-docs.sh dev

Then build the HTML site:

sphinx-build docs target/doc

The output is written to target/doc/.

How to fix code formatting?

cargo fmt

To only check without modifying files:

cargo fmt --check

How to lint?

cargo clippy -- -D warnings

To automatically apply safe fixes:

cargo clippy --fix --allow-dirty

How to run a security audit?

cargo audit

How to create a good pull request?

High quality pull requests are easier to review and thus take less of your and our time.

General guideline:

  • Each pull request must have exactly one intent (fix a bug, update doc, etc.).
  • Each pull request should have one Git commit (not mandatory, but recommended).
  • Each Git commit must have a descriptive message that explains the changes.
  • Each Git commit must have a sign-off (git commit --signoff), which indicates that you agree with the Developer Certificate of Origin.
  • Each Git commit message must start with either:
    • feat: ... for features
    • fix: ... for bug and security fixes
    • perf: ... for performance improvements
    • refactor: ... for code refactorings
    • style: ... for formatting or whitespace changes with no logic change
    • docs: ... for documentation changes
    • test: ... for adding or correcting tests
    • build: ... for build system or dependency changes
    • ci: ... for CI/CD pipeline changes
    • chore: ... for changes not related to source code
    • revert: ... for reverting a previous commit

Before opening a pull request, please verify that your changes pass all checks:

cargo fmt --check && cargo clippy -- -D warnings && cargo test && cargo audit

What license does Cubic use?

Cubic is dual-licensed under the MIT and Apache 2.0 licenses. By submitting a pull request, you agree that your contribution is licensed under these licenses.