Thank you for your interest in Flame. Contributions of all kinds are welcome: bug reports, feature requests, documentation, and code.
Contributions are made under the Apache License 2.0, the license of the project.
- Report a bug or request an enhancement in the issue tracker. Pick the bug report or feature request template.
- Ask a question or discuss an idea in GitHub Discussions.
- Report a security vulnerability privately; see SECURITY.md. Do not open a public issue for it.
- Send a pull request for a fix, a feature or documentation.
Search the existing issues first. A good report has the version of Flame
(flmctl --version, or the image tag), the operating system and how Flame was
installed, the steps to reproduce, what you expected, and what happened,
including the relevant logs (flmctl list -s, flmctl list -e, and the logs of
the session manager and the executor manager). The bug report template asks
for these. A maintainer will respond on the issue. Reports are public, which
is why vulnerabilities go through SECURITY.md instead.
Describe the problem you want to solve before the solution. Larger changes
(a new scheduling policy, a protocol change, a new component) start with a
design document in docs/designs, following the RFE<issue>
pattern of the existing ones, so that the design is reviewed before the code.
The README has the quick start, and
Local Development sets up a
single-node cluster from the source tree. You need the Rust toolchain
(rust-toolchain.toml pins it), protoc, and, for the Python SDK, Python and
uv.
make update_protos # copy the protobuf files into the SDKs
cargo build --workspace --exclude flame-rs- Rust: formatted with
cargo fmt(seerustfmt.toml) and free ofcargo clippywarnings; CI runs clippy with-D warnings. - Python: formatted and linted with
ruff(seesdk/python/pyproject.toml). - Match the style of the code around your change: naming, comment density and idioms. Keep a change small and focused; do not mix a refactoring with a fix.
- New source files carry the Apache license header like the existing ones.
- Update the documentation (
docs/, a crate's README, doc comments) together with the behavior that it describes.
Run the same checks as CI before you send a pull request:
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --workspace --exclude flame-rs
cd sdk/python
uv run --extra dev ruff format --check src tests
uv run --extra dev ruff check src tests
uv run --extra dev --with numpy pytest testsA change that adds or changes functionality, or fixes a bug, must come with tests. A bug fix includes a test that fails without the fix. A pull request without tests needs a reason in its description (for example a documentation change, or behavior that only a cluster can show), and a reviewer may ask for the test anyway.
- Rust: unit tests next to the code (
#[cfg(test)] mod tests) and the integration tests of a crate. - Python SDK:
sdk/python/tests. - End-to-end and system tests, which run against a cluster:
testing/e2eandtesting/system(see their README files).
The tests run automatically on every pull request (see
.github/workflows), on the host shim, the CRI shim and Kubernetes. All the
checks must pass before a pull request is merged.
- Fork the repository and create a branch from
main. - Make the change, with its tests and documentation.
- Run the checks above.
- Open a pull request against
mainand fill in the template. Link the issue that it fixes (Fixes #123). - A maintainer reviews it. Address the comments by pushing to the same branch; the pull request is squash-merged, so its history does not need to be tidy.
Use a short commit subject with a conventional prefix, as in the history:
feat:, fix:, docs:, test:, chore:, refactor:, perf: or ci:.
Changes to a release branch (release-0.7, ...) are cherry-picks of changes
that were merged to main first; see the release process.