Contributing to killpy

July 21, 2026 · View on GitHub

Thank you for wanting to improve killpy! Contributions of all kinds are welcome — bug reports, feature ideas, documentation fixes, and pull requests.

Quick start

# 1. Fork the repo on GitHub, then clone your fork
git clone https://github.com/<your-username>/killpy.git
cd killpy

# 2. Install with development dependencies (uv recommended)
pip install -e ".[dev]"
# or
uv sync

# 3. Verify everything works
python -m compileall killpy
pytest tests/

Development workflow

Create a branch off master (or main):
```
git checkout -b feat/my-feature
```
Make focused, minimal changes — avoid refactoring unrelated code.
Run tests before committing:
```
pytest tests/
```
Run the linter / type checker if available:
```
ruff check killpy
mypy killpy
```

Write a commit message following Conventional Commits:

feat: add --exclude option to skip path patterns
fix: handle missing conda command gracefully
docs: update keybindings table in README

Open a pull request against master with a clear description of what and why.

Detectors live in killpy/detectors/. Each one inherits from AbstractDetector in base.py, declares its can_handle() contract as data (required_tool / always_available / _candidate_dirs), and implements detect().

from killpy.detectors.base import AbstractDetector
from killpy.models import Environment

class MyToolDetector(AbstractDetector):
    name = "mytool"
    required_tool = "mytool"  # or always_available = True, or override _candidate_dirs()

    def detect(self, path: Path) -> list[Environment]:
        # return a list of Environment objects
        ...

Then register it in killpy/detectors/__init__.py (import it, add it to __all__ and to ALL_DETECTORS).

Full step-by-step guide: dev-docs/ADDING_A_DETECTOR.md.

Coding conventions & architecture

Before making non-trivial changes, read the internal reference docs — they declare the conventions this codebase follows and why:

dev-docs/CODING_CONVENTIONS.md — the rules (naming, error handling, detectors, models, logging, …) with correct/avoid examples and the tooling that enforces them.
dev-docs/ARCHITECTURE_ANALYSIS.md — a diagnostic of the layering and known trade-offs.
dev-docs/ADDING_A_DETECTOR.md — the detector cookbook.

Recording a demo GIF

A compelling demo GIF is one of the best ways to showcase new features.

Recommended setup:

Terminal: 100 × 30 characters, dark theme
Tool: vhs or asciinema + agg
Content: show scanning, filtering with /, multi-selecting with T/Space, and deleting

Update show.gif in the repo root and reference it in README.md.

Good first issues

Look for issues labelled good first issue — these are intentionally scoped to be approachable for new contributors.

Code of conduct

Be respectful and constructive. We follow the Contributor Covenant.