Your First Contribution

This tutorial walks you through making your first code contribution to HealthArchive, from setup to merged pull request.

Time: 30-45 minutes Prerequisites: - Git installed - Python 3.11+ installed - Basic command line knowledge - GitHub account

Step 1: Fork and Clone

Fork the repository on GitHub:
Visit github.com/jerdaw/healtharchive
Click "Fork" in the top-right corner

Clone your fork:

git clone https://github.com/YOUR-USERNAME/healtharchive.git
cd healtharchive

Add upstream remote (to sync with the main repo later):

git remote add upstream https://github.com/jerdaw/healtharchive.git

Verify remotes:

git remote -v
# Should show:
# origin    https://github.com/YOUR-USERNAME/healtharchive.git (fetch)
# origin    https://github.com/YOUR-USERNAME/healtharchive.git (push)
# upstream  https://github.com/jerdaw/healtharchive.git (fetch)
# upstream  https://github.com/jerdaw/healtharchive.git (push)

Step 2: Set Up Your Development Environment

Create a virtual environment and install dependencies:
```
make venv
```

This command: - Creates .venv/ directory - Installs all Python dependencies - Installs development tools (pytest, ruff, mypy, pre-commit)

Activate the virtual environment:
```
source .venv/bin/activate
```
Copy the example environment file:
```
cp .env.example .env
```

Edit .env with your local paths (optional, defaults work for most cases):

# Example local settings
HEALTHARCHIVE_DATABASE_URL=sqlite:///$(pwd)/.dev-healtharchive.db
HEALTHARCHIVE_ARCHIVE_ROOT=$(pwd)/.dev-archive-root
HEALTHARCHIVE_LOG_LEVEL=INFO

Source the environment:
```
source .env
```
Run database migrations:
```
alembic upgrade head
```
Seed initial data:
```
healtharchive seed-sources
```

Step 3: Verify Your Setup

Run the fast CI checks to ensure everything works:

make ci

This runs: - ruff check (linting) - mypy (type checking) - pytest (tests)

Expected output: All checks should pass ✅

If anything fails, review the error messages and check: - Python version is 3.11+ - Virtual environment is activated - Dependencies installed correctly

Step 4: Find a Good First Issue

Browse issues labeled good first issue:
Visit github.com/jerdaw/healtharchive/issues?q=is:issue+is:open+label:"good+first+issue"
Pick an issue that interests you:
Look for clear descriptions
Check if anyone is already working on it
Comment on the issue to claim it
No good first issues available? Try:
Fix a typo in documentation
Add a test for an existing function
Improve error messages or log output

For this tutorial, we'll add a simple CLI command as an example.

Step 5: Create a Feature Branch

Sync with upstream (ensure you have latest changes):
```
git checkout main
git pull upstream main
```
Create a new branch (use a descriptive name):
```
git checkout -b add-version-command
```

Branch naming conventions: - add-* for new features - fix-* for bug fixes - docs-* for documentation changes - refactor-* for code refactoring

Step 6: Make Your Change

Let's add a simple --version command to the CLI.

Open src/ha_backend/cli.py in your editor

Add a version command (example change):

@cli.command()
def version():
    """Display version information."""
    import ha_backend
    from ha_backend.logging_config import setup_logging

    setup_logging()
    logger = logging.getLogger(__name__)

    # You would import from a version module in a real implementation
    version_string = "0.1.0"  # Placeholder
    logger.info(f"HealthArchive Backend version {version_string}")
    print(f"HealthArchive Backend v{version_string}")

Test your change manually:

healtharchive version
# Should output: HealthArchive Backend v0.1.0

Step 7: Write Tests

Every code change needs tests. Let's write a test for our new command.

Create or update test file: tests/test_cli_<your_feature>.py

"""Tests for version CLI command."""
import subprocess


def test_version_command():
    """Test that version command runs and outputs version info."""
    result = subprocess.run(
        ["healtharchive", "version"],
        capture_output=True,
        text=True,
    )

    assert result.returncode == 0
    assert "HealthArchive Backend" in result.stdout
    assert "0.1.0" in result.stdout

Run the test:

pytest tests/test_cli_<your_feature>.py -v

Verify it passes:

tests/test_cli_version.py::test_version_command PASSED

Step 8: Run All Checks

Before submitting, ensure all checks pass:

make ci

This runs: 1. Format check: ruff format --check . 2. Lint: ruff check . 3. Type check: mypy . 4. Tests: pytest

Fix any failures before proceeding.

Common fixes: - Formatting issues: Run make format to auto-fix - Linting issues: Fix manually or run ruff check --fix . - Type errors: Add type hints or fix type mismatches - Test failures: Fix the code or update tests

Step 9: Commit Your Changes

Stage your changes:

git add src/ha_backend/cli/main.py tests/test_cli_version.py

Commit with a clear message:

git commit -m "feat: add version command to CLI

- Add 'healtharchive version' command
- Display version information
- Add test coverage for version command

Closes #123"

Commit message conventions: - First line: type: short description (50 chars or less) - Types: feat, fix, docs, test, refactor, chore - Body: Explain what and why (not how) - Footer: Reference issues with Closes #123

Step 10: Push and Create Pull Request

Push your branch to your fork:
```
git push origin add-version-command
```
Create a pull request on GitHub:
Visit your fork on GitHub
Click "Compare & pull request" button
Fill in the PR template:
- Title: Clear, concise description
- Description: What changed and why
- Testing: How you verified it works
- Checklist: Complete all items

Example PR description:

## Summary
Adds a `--version` command to display backend version information.

## Changes
- Added `version` command to CLI
- Added test coverage in `tests/test_cli_version.py`

## Testing
- ✅ Manual testing: `healtharchive version` outputs correct version
- ✅ All CI checks pass
- ✅ New tests added and passing

## Related Issues
Closes #123

Wait for CI checks to run on your PR (takes ~5 minutes)
Address review feedback if requested

Step 11: Respond to Review Feedback

When maintainers review your PR, they may request changes:

Make the requested changes:

# Still on your feature branch
vim src/ha_backend/cli/main.py

Commit the changes:

git add .
git commit -m "fix: address review feedback

- Improve version output formatting
- Add docstring details"

Push updates:
```
git push origin add-version-command
```

The PR will update automatically!

Reply to review comments to acknowledge feedback

Step 12: Merge and Celebrate! 🎉

Once approved:

A maintainer will merge your PR
Your contribution is now part of HealthArchive!
Your GitHub profile will show the contribution

Optional: Clean up your local branches:

git checkout main
git pull upstream main
git branch -d add-version-command

Tips for Success

Code Quality

✅ Follow existing code style and patterns
✅ Add type hints to all functions
✅ Write clear docstrings
✅ Keep changes focused and small

Testing

✅ Write tests for all new code
✅ Ensure tests are deterministic (no flaky tests)
✅ Use fixtures for test data
✅ Test edge cases and error conditions

Communication

✅ Ask questions if unclear
✅ Keep PR descriptions detailed
✅ Respond to feedback promptly
✅ Be respectful and collaborative

Common Pitfalls to Avoid

❌ Don't commit directly to main
❌ Don't include unrelated changes in one PR
❌ Don't skip writing tests
❌ Don't ignore CI failures

Next Steps

After your first contribution:

Tackle more issues: Graduate to help wanted issues
Learn the architecture: Read the Architecture Walkthrough
Improve the docs: Documentation PRs are always welcome
Review others' PRs: Great way to learn and help the community

Getting Help

Questions about the code? Ask in the issue thread
CI failures? Check the Testing Guidelines
Architecture questions? Read the Architecture Guide
Still stuck? Open a discussion on GitHub

Resources

Welcome to the HealthArchive community! 🚀