Contributing to PID Pal

Thank you for your interest in contributing to PID Pal! This document provides guidelines for contributing to the project.

Getting Started

Development Setup

Fork and clone the repository

git clone https://github.com/MSNYC/pidpal.git
cd pidpal

Create a virtual environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install development dependencies
```
pip install -e ".[dev]"
```

Set up API keys for testing (optional)

export ANTHROPIC_API_KEY="your-test-key"
export OPENAI_API_KEY="your-test-key"

Run tests to verify setup
```
pytest tests/
```

Ways to Contribute

1. Expanding the Knowledge Base

The easiest and most valuable contribution! Add entries to src/pidpal/knowledge/binaries.json:

{
  "process_name": {
    "description": "Clear, concise description of what this process does",
    "role": "daemon|user_app|system_service|helper|worker|shell",
    "origin": "os|package_manager|user_launch|dependency",
    "scope": "system_wide|session_bound|user_specific",
    "system_critical": false,
    "normal": true,
    "attention_worthy": false,
    "tags": ["relevant", "descriptive", "tags"],
    "notes": "Any additional context or common issues"
  }
}

Guidelines:

Focus on commonly seen processes
Write descriptions for a general audience (not experts only)
Be accurate - verify information
Include typical use cases in notes
Tag appropriately for searchability

2. Improving Heuristics

Enhance process interpretation in src/pidpal/core/interpreter.py:

Better role classification logic
Origin detection improvements
Attention-worthy detection
Parent relationship analysis

3. Bug Fixes

Found a bug? Great!

Check if an issue already exists
Create a new issue if not
Fork, fix, test, and submit a PR

4. New Features

For new features:

Check the roadmap to see if it's planned
Open an issue to discuss the feature first
Get approval from maintainers
Implement with tests
Submit a PR

5. Documentation

Documentation improvements are always welcome:

Fix typos or unclear explanations
Add examples
Improve usage guides
Write tutorials

6. Testing

Add test coverage for untested code
Add test cases for edge conditions
Improve test fixtures

Development Workflow

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Branch naming:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
refactor/ - Code refactoring
test/ - Test additions/improvements

2. Make Changes

Write clean, readable code
Follow the existing code style
Add/update tests
Update documentation

3. Run Quality Checks

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/pidpal

# Run tests
pytest tests/

# Check coverage
pytest tests/ --cov=pidpal --cov-report=html

4. Commit

Write clear commit messages:

Add knowledge base entry for nginx

- Added comprehensive nginx process information
- Included common configuration notes
- Tagged with web-server and network

Format:

First line: Brief summary (50 chars or less)
Blank line
Detailed description (wrap at 72 chars)

5. Push and Create PR

git push origin feature/your-feature-name

Then create a Pull Request on GitHub with:

Clear title
Description of changes
Link to related issues
Screenshots/examples if applicable

Code Style Guidelines

Python Style

We follow PEP 8 with some modifications:

Line length: 100 characters (enforced by Black)
Use type hints where helpful
Docstrings for public functions/classes
Clear variable names (no abbreviations)

Code Organization

# Imports: standard library, third-party, local
import os
from typing import Optional

import click
from anthropic import Anthropic

from pidpal.core.observer import ProcessData

# Constants at module level
DEFAULT_TIMEOUT = 30

# Classes and functions
class MyClass:
    """Clear docstring explaining the class."""

    def my_method(self, param: str) -> bool:
        """
        Clear docstring explaining the method.

        Args:
            param: Description of parameter

        Returns:
            Description of return value
        """
        pass

Documentation Style

Use Google-style docstrings:

def explain_process(pid: int, verbose: bool = False) -> str:
    """
    Explain a process in human-readable language.

    Args:
        pid: Process ID to explain
        verbose: Include detailed technical information

    Returns:
        Human-readable explanation string

    Raises:
        ProcessNotFoundError: If process doesn't exist
        PermissionError: If insufficient permissions
    """
    pass

Testing Guidelines

Writing Tests

import pytest
from pidpal.core.observer import ProcessObserver

def test_observer_with_valid_pid():
    """Test that observer collects data for valid PID."""
    observer = ProcessObserver()
    data = observer.observe(1)  # PID 1 always exists

    assert data.pid == 1
    assert data.name is not None

def test_observer_with_invalid_pid():
    """Test that observer raises error for invalid PID."""
    observer = ProcessObserver()

    with pytest.raises(ProcessNotFoundError):
        observer.observe(999999)

Test Coverage Goals

New features: 100% coverage
Bug fixes: Add test that would have caught the bug
Overall project: >80% coverage

Running Specific Tests

# Run specific test file
pytest tests/test_observer.py

# Run specific test
pytest tests/test_observer.py::test_observer_with_valid_pid

# Run with verbose output
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=pidpal

Pull Request Process

Before Submitting

Code follows style guidelines
Tests pass (pytest tests/)
Code is formatted (black src/ tests/)
Linting passes (ruff check src/ tests/)
Type checking passes (mypy src/pidpal)
Documentation updated
Changelog entry added (if applicable)

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Test improvement

## Related Issues
Fixes #123

## Testing
Describe how you tested your changes

## Checklist
- [ ] Tests pass
- [ ] Code formatted (black)
- [ ] Linting passes (ruff)
- [ ] Documentation updated

Review Process

Maintainer reviews PR
Feedback provided (if needed)
You address feedback
Maintainer approves
PR merged to main

Knowledge Base Contributions

Guidelines for Process Entries

Research the process:

Run it yourself if possible
Check official documentation
Verify typical behavior
Note common issues

Write clear descriptions:

Avoid jargon (or explain it)
Explain in terms users understand
Focus on "what" and "why"
Be concise but complete

Classify accurately:

Role: What type of process is this?
- daemon: Background service
- user_app: User-launched application
- system_service: OS service
- helper: Assists another process
- worker: Does background tasks
- shell: Command interpreter
Origin: Where does it come from?
- os: Part of operating system
- package_manager: Installed via apt/yum/etc
- user_launch: User started it
- dependency: Started by another process
Scope: What's its reach?
- system_wide: Affects whole system
- session_bound: Tied to user session
- user_specific: Just for one user

Tag thoughtfully:

Common tags: network, security, desktop, audio, video, development, database, web-server
Add new tags if needed
2-5 tags is usually right

Example of a great entry:

{
  "postgres": {
    "description": "PostgreSQL database server",
    "role": "daemon",
    "origin": "package_manager",
    "scope": "system_wide",
    "system_critical": false,
    "normal": true,
    "attention_worthy": false,
    "tags": ["database", "server", "sql"],
    "notes": "PostgreSQL is a popular open-source relational database. Multiple postgres processes are normal - one main process and several worker processes. High memory usage is expected when serving many connections or large queries."
  }
}

Reporting Issues

Bug Reports

Include:

PID Pal version (pidpal --version)
Operating system and version
Python version
Steps to reproduce
Expected vs actual behavior
Error messages (full output)
Relevant process information

Feature Requests