Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
219 lines (154 loc) · 5.96 KB

CONTRIBUTING.md

File metadata and controls

219 lines (154 loc) · 5.96 KB

Contributing to CORTEX

Thank you for your interest in contributing to CORTEX. This guide covers everything you need to get started.

Table of Contents

Code of Conduct

This project follows the Contributor Covenant v2.1. By participating, you are expected to uphold this code. Please report unacceptable behavior to security@cortex-project.dev.

Prerequisites

Before you begin, make sure you have the following installed:

Tool Version Notes
Rust 1.75+ (nightly) Required for io_uring and unstable features
Go 1.21+ For Kubernetes components
Python 3.11+ With Poetry for dependency management
Node.js 20+ With pnpm for the dashboard
NVIDIA Drivers Latest stable With NVML support for GPU topology discovery
Linux Kernel 5.19+ Required for io_uring features

Optional

  • Docker / Podman -- For containerized builds and testing
  • kubectl + kind or minikube -- For Kubernetes integration testing
  • DPDK 22.11+ -- For kernel bypass networking development

Development Setup

# Clone the repository
git clone https://github.com/milyas2001/cortex.git
cd cortex

# Install Rust nightly toolchain
rustup toolchain install nightly
rustup override set nightly

# Install Go dependencies
cd kubernetes && go mod download && cd ..

# Install Python dependencies
cd autoscaler && poetry install && cd ..

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

Building

# Build everything
make all

# Build individual components
make build-rust          # Scheduler, network, memory, energy
make build-go            # Kubernetes extender, device plugin, metrics server
make build-dashboard     # React dashboard
make install-autoscaler  # Python autoscaler

Testing

# Run all Rust tests
cargo test

# Run tests for a specific crate
cargo test -p cortex-scheduler
cargo test -p cortex-memory
cargo test -p cortex-network
cargo test -p cortex-energy

# Run Go tests
cd kubernetes && go test ./... && cd ..

# Run Python tests
cd autoscaler && poetry run pytest && cd ..

# Run benchmarks
cargo bench
cargo bench --bench scheduler_bench
cargo bench --bench memory_bench

Code Style

Rust

  • Format with rustfmt: cargo fmt --all
  • Lint with clippy: cargo clippy --all-targets --all-features -- -D warnings
  • Use unsafe sparingly and document every usage with a // SAFETY: comment
  • All public APIs must have doc comments

Go

  • Format with gofmt: gofmt -w .
  • Lint with golangci-lint: golangci-lint run ./...
  • Follow Effective Go conventions

Python

  • Format with black: black .
  • Lint with ruff: ruff check .
  • Type check with mypy: mypy .
  • Target Python 3.11+ type annotation syntax

TypeScript

  • Lint with eslint: pnpm lint
  • Format with prettier: pnpm format
  • Strict mode enabled in tsconfig.json

Commit Convention

We follow the Conventional Commits specification.

Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

Type Description
feat A new feature
fix A bug fix
docs Documentation changes
style Code style changes (formatting, no logic change)
refactor Code restructuring without feature or fix
perf Performance improvements
test Adding or updating tests
build Build system or dependency changes
ci CI configuration changes
chore Maintenance tasks

Scopes

Use the component name as the scope: scheduler, network, memory, autoscaler, energy, kubernetes, dashboard.

Examples

feat(scheduler): add NVLink bandwidth-aware placement scoring
fix(memory): prevent buddy allocator double-free on coalesce
docs(readme): update kernel bypass networking diagram
perf(network): reduce io_uring submission latency by batching SQEs
test(autoscaler): add Prophet forecast accuracy regression tests

Pull Request Process

  1. Fork the repository and create a branch from main.
  2. Name your branch using the pattern: <type>/<short-description> (e.g., feat/nvlink-bandwidth-scoring).
  3. Write tests for any new functionality.
  4. Run the full test suite and ensure all checks pass.
  5. Update documentation if your change affects public APIs or user-facing behavior.
  6. Open a pull request against main and fill out the PR template.
  7. Address review feedback by pushing additional commits (do not force-push during review).
  8. A maintainer will merge your PR once it is approved and CI passes.

What We Look For

  • Tests covering new behavior and edge cases
  • No regressions in existing benchmarks
  • Clear commit history following conventional commits
  • Documentation for public-facing changes
  • unsafe code reviewed with // SAFETY: annotations

Issue Guidelines

  • Bug reports: Include OS, kernel version, GPU model, driver version, and steps to reproduce.
  • Feature requests: Describe the use case and proposed approach.
  • Questions: Use GitHub Discussions instead of issues.

Use the provided issue templates when opening a new issue.

License Agreement

By submitting a pull request, you agree that your contribution will be licensed under the MIT License, the same license that covers this project. See LICENSE for the full text.