Skip to content
GreenKube

Contributing

GreenKube is an open-source, community-driven project. We welcome contributions from everyone, especially new recommendation sources and support for more GitOps layouts.

🐛 Report Bugs

Found a bug? Open an Issue with a detailed description, steps to reproduce, and expected behavior.

💡 Suggest Features

Have an idea? Start a Discussion to propose and discuss new features with the community.

🔧 Submit Code

Ready to code? Fork the repo, create a branch, make your changes, and submit a Pull Request.

📖 Improve Docs

Documentation improvements are always welcome! Fix typos, add examples, or write new guides.

  • Python 3.13+
  • Node.js 20+ (for frontend development)
  • Git
Terminal window
# Clone the repository
git clone https://github.com/GreenKubeCloud/GreenKube.git
cd GreenKube
# Install uv (if not already installed)
pip install uv
# or: curl -LsSf https://astral.sh/uv/install.sh | sh
# Create virtual environment and install all dependencies (dev + test)
uv sync
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# Install pre-commit hooks
pre-commit install
# Run tests to verify everything works
uv run pytest
Terminal window
cd frontend
npm install
npm run dev # Start dev server with hot reload
npm run build # Build for production
  • Database Agnosticism: Use repository interfaces, never import storage-specific code in core/
  • Factory Pattern: Instantiate repositories via core/factory.py
  • Dependency Injection: Pass repositories to use cases as parameters
  • All I/O is async: Use async def for network, database, and file operations
  • Always await: Never use sync wrappers for async operations
  • Concurrent execution: Use asyncio.gather for parallel operations
  • Connection pooling: Reuse HTTP clients and database pools
  • Never crash the pipeline — Log errors with context and continue
  • Use default values on failure — Flag as is_estimated: true
  • Standard logging: Use logging.getLogger(__name__)
Terminal window
# Format code
uv run ruff format .
# Lint code
uv run ruff check .
# Auto-fix lint issues
uv run ruff check --fix .
# Type-check with Pyrefly
uv run pyrefly check
# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=greenkube --cov-report=html
LevelUse Case
DEBUGDetailed flow, cache hits, parsing details
INFOMajor pipeline events, collection start/end
WARNINGRecoverable issues, fallback to defaults
ERRORFailures requiring attention

Follow Conventional Commits:

feat: add GPU power profiling
fix: handle missing node labels gracefully
docs: add storage backend comparison
test: add unit tests for rightsizing recommendations
refactor: extract zone mapping to utility module
perf: optimize batch database inserts
  1. Fork the repository
  2. Create a branch from main: git checkout -b feat/my-feature
  3. Write tests for your changes (TDD approach)
  4. Run the test suite and ensure all tests pass
  5. Format and lint your code with Ruff
  6. Commit with a conventional commit message
  7. Push to your fork and open a Pull Request
  8. Describe your changes and link relevant issues
  • Tests pass (pytest)
  • Code is formatted (ruff format --check .)
  • Code passes lint (ruff check .)
  • New features have tests
  • Documentation is updated (if applicable)
  • Commit messages follow conventional commits
  • A new recommendation source. Implement a Source (discover, health, collect) that emits signals, package it under the greenkube.sources entry point group, and run the contract test suite. See Sources overview and the example package.
  • A new GitOps layout. Unsupported layouts fail closed with a typed reason; the GitOps delivery page lists what is supported today.
  • The end-to-end loop. make e2e runs the whole loop on Minikube with a sample app, Argo CD, Flux and Gitea (Quick Start).

The repository’s CONTRIBUTING.md is the reference for the development workflow.

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