Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
83 lines (63 loc) · 2.44 KB

CONTRIBUTING.md

File metadata and controls

83 lines (63 loc) · 2.44 KB

Contributing to Good Egg

Setup

# Clone
git clone https://github.com/2ndSetAI/good-egg.git
cd good-egg

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

Project Structure

good-egg/
├── src/good_egg/
│   ├── action.py         # GitHub Action entry point
│   ├── cache.py          # SQLite-backed response cache
│   ├── cli.py            # Click CLI (good-egg score, cache-stats, cache-clear)
│   ├── config.py         # YAML + env var configuration
│   ├── exceptions.py     # Custom exception hierarchy
│   ├── formatter.py      # Markdown, CLI, JSON, check-run formatters
│   ├── github_client.py  # Async GitHub GraphQL/REST client with retry
│   ├── graph_builder.py  # Bipartite trust graph construction
│   ├── mcp_server.py     # MCP server for AI assistant integration
│   ├── models.py         # Pydantic data models
│   └── scorer.py         # Graph-based trust scoring engine
├── tests/                # pytest test suite
├── scripts/
│   └── validate_scoring.py  # Validation against real repos
├── docs/                 # Documentation (library, action, MCP, config)
├── examples/             # Example workflows and config files
└── CHANGELOG.md          # Release history

Development Workflow

# Run tests
uv run pytest --cov=good_egg -v

# Lint
uv run ruff check src/ tests/ scripts/

# Type check
uv run mypy src/good_egg/

# Format (auto-fix)
uv run ruff check --fix src/ tests/ scripts/

# Verify packaging
uv build

Code Style

  • Ruff enforces style (E, F, I, N, W, UP, B, A, SIM rules)
  • Line length: 99 characters
  • Type annotations required on all function signatures (mypy strict)
  • Use from __future__ import annotations in every module

Running the Validation Suite

The validation script scores real PR authors from popular repos to check scoring methodology:

GITHUB_TOKEN=$(gh auth token) uv run python scripts/validate_scoring.py --sample-size 5

This requires gh CLI authenticated. Results are written to the validation/ directory.

Pull Requests

  1. Create a feature branch from main
  2. Make your changes with tests
  3. Ensure uv run pytest --cov=good_egg -v passes with >= 90% coverage
  4. Ensure uv run ruff check src/ tests/ scripts/ is clean
  5. Open a PR with a clear description