Skip to content
GreenKube

Contributing

GreenKube is an open-source, community-driven project. We welcome contributions from everyone!

Ways to Contribute

Section titled “Ways to Contribute”

🐛 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.

Development Setup

Section titled “Development Setup”

Prerequisites

Section titled “Prerequisites”
  • Python 3.9+
  • Node.js 20+ (for frontend development)
  • Git

Getting Started

Section titled “Getting Started”
Terminal window
# Clone the repository
git clone https://github.com/GreenKubeCloud/GreenKube.git
cd GreenKube


# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows


# Install with development and test dependencies
pip install -e '.[test,dev]'


# Install pre-commit hooks
pre-commit install


# Run tests to verify everything works
pytest

Frontend Development

Section titled “Frontend Development”
Terminal window
cd frontend
npm install
npm run dev    # Start dev server with hot reload
npm run build  # Build for production

Code Guidelines

Section titled “Code Guidelines”

Architecture Rules

Section titled “Architecture Rules”
  • 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

Async Best Practices

Section titled “Async Best Practices”
  • 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

Error Handling

Section titled “Error Handling”
  • 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__)

Code Quality

Section titled “Code Quality”
Terminal window
# Format code
ruff format .


# Lint code
ruff check .


# Auto-fix lint issues
ruff check --fix .


# Run tests
pytest


# Run tests with coverage
pytest --cov=greenkube --cov-report=html

Logging Levels

Section titled “Logging Levels”
LevelUse Case
DEBUGDetailed flow, cache hits, parsing details
INFOMajor pipeline events, collection start/end
WARNINGRecoverable issues, fallback to defaults
ERRORFailures requiring attention

Commit Convention

Section titled “Commit Convention”

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

Pull Request Process

Section titled “Pull Request Process”
  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

PR Checklist

Section titled “PR Checklist”
  • 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

Adding New Features

Section titled “Adding New Features”

New Collector

Section titled “New Collector”
  1. Create src/greenkube/collectors/my_collector.py
  2. Implement async collect() method
  3. Register in core/factory.py
  4. Update DataProcessor to call the collector
  5. Add unit tests in tests/collectors/

New Storage Backend

Section titled “New Storage Backend”
  1. Implement abstract classes from storage/base_repository.py
  2. Register in core/factory.py backend mapping
  3. Add schema migration logic
  4. Add unit tests in tests/storage/

New Cloud Provider

Section titled “New Cloud Provider”
  1. Add region mappings to utils/region_mapping.py
  2. Add instance power profiles to energy/instance_profiles.py
  3. Add PUE values to core/config.py
  4. Update tests

Community

Section titled “Community”

License

Section titled “License”

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