Contributing to KruxOS¶

KruxOS is open source under the Apache 2.0 license. Contributions are welcome.

Ways to contribute¶

Contribution	Where
Bug reports	GitHub Issues
Feature requests	GitHub Discussions
Code contributions	Pull requests
Capability packs	Pack Registry
Documentation	Pull requests to `docs/`

Development setup¶

Prerequisites¶

Rust 1.75+ (stable toolchain)
Python 3.11+
Node.js 20+ (for dashboard and pack CLI)
Docker (for integration tests and benchmarks)

Build from source¶

git clone https://github.com/altvale/kruxos.git
cd kruxos

# Build all Rust crates
cargo build

# Install Python SDK in development mode
cd sdk/python && pip install -e ".[dev]" && cd ../..

# Install dashboard dependencies
cd dashboard && npm install && cd ..

# Install pack CLI
cd pack-sdk/cli && npm install && cd ../..

Run tests¶

# Rust unit tests
cargo test

# Python SDK tests
cd sdk/python && pytest && cd ../..

# Dashboard tests
cd dashboard && npm test && cd ..

# Integration tests (requires Docker)
cargo test --features integration

# Benchmarks
cd benchmarks && python runner.py run --platform kruxos --runs 1

Code standards¶

Rust¶

Edition 2021, stable toolchain
thiserror for error types, anyhow for application errors
tokio async runtime, tracing for logging
All public APIs documented with /// doc comments
All modules have #[cfg(test)] mod tests
Run cargo clippy — no warnings
Run cargo fmt — consistent formatting

Python¶

Python 3.11+, type hints everywhere
pydantic for data models
pytest for testing, ruff for linting
All public functions have docstrings

Capability definitions (YAML)¶

Follow the Documentation Standard
Every capability has: purpose, when_to_use, inputs, outputs, side_effects, common_patterns, errors
Descriptions written for AI consumption — concrete, literal, no metaphors

Pull request process¶

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Make your changes
Add tests for new functionality
Run the full test suite: cargo test && pytest
Commit with a descriptive message
Push to your fork
Open a pull request

PR guidelines¶

Keep PRs focused — one feature or fix per PR
Include tests for new code
Update documentation if the user-facing behaviour changes
Add entries to the YAML definitions if adding capabilities
Don't break existing tests

Commit message format¶

[COMPONENT] Brief description

What was built or changed:
- File changes and their purpose

Test summary:
- What tests were added/modified
- Test results

Architecture decisions¶

If your contribution involves a significant design decision, open a Discussion first. The project maintains a DECISIONS.md file tracking all deviations from the original specification.

Security¶

To report a security vulnerability, email [email protected]. Do not file a public issue.

License¶

By contributing, you agree that your contributions will be licensed under the Apache 2.0 license.