Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
120 lines (83 loc) · 3.62 KB

CONTRIBUTING.md

File metadata and controls

120 lines (83 loc) · 3.62 KB
Raw

Contributing

This document explains how to set up a development environment and contribute code to the jkp-data repository.

Development Setup

  1. Clone the repository

    git clone https://github.com/bkelly-lab/jkp-data.git
cd jkp-data

  2. Install dependencies

    Install all development dependencies using your preferred Python package manager. With uv:

    uv sync --group dev --group test --group lint

    This installs the base dependencies plus tools for testing (pytest, pytest-cov) and linting (ruff, pyright).

Note: The commands below assume the project's dependencies are available in your current environment. The exact invocation may vary slightly depending on your package manager — for example, you may need to activate a virtualenv first, or prefix commands with uv run if using uv.

Running Tests

Tests live in the tests/ directory. Run them with:

# Run all tests with coverage
pytest

# Run with verbose output
pytest -v

# Run a specific test file
pytest tests/unit/test_expressions.py

Coverage is enabled by default. After each run, you'll see which lines of code were exercised by tests.

For detailed guidance on writing tests, see tests/README.md.

Code Style

We use ruff for linting and formatting. Before submitting a PR:

# Check for lint errors
ruff check src/jkp/data/ tests/

# Auto-fix what can be fixed
ruff check --fix src/jkp/data/ tests/

# Check formatting
ruff format --check src/jkp/data/ tests/

# Auto-format
ruff format src/jkp/data/ tests/

Type Checking

We use pyright for static type checking:

pyright src/jkp/data/

Pyright runs in CI but does not currently block PRs. It surfaces potential bugs and type inconsistencies. If you see errors related to your changes, consider fixing them.

Pull Request Process

  1. Create a branch for your changes

  2. Write tests for new functionality or bug fixes. See tests/README.md for guidance.

  3. Run tests locally before pushing:

    pytest

  4. Run the linter and fix any issues:

    ruff check src/jkp/data/ tests/
ruff format --check src/jkp/data/ tests/

  5. Push and open a PR. The CI pipeline will run automatically.

  6. All checks must pass before merging. This includes:

    • Ruff lint and format checks
    • All unit tests passing on Python 3.11 and 3.12

Project Structure

jkp-data/
├── src/
│   └── jkp/                    # Namespace package (no __init__.py)
│       └── data/               # Main source package
│           ├── __init__.py
│           ├── cli.py           # CLI entry point (jkp command)
│           ├── aux_functions.py # Core utility functions and characteristics
│           ├── main.py          # Pipeline orchestration
│           ├── portfolio.py     # Factor portfolio construction
│           ├── config.py        # Pipeline configuration
│           ├── wrds_credentials.py # WRDS credential management
│           └── wrds_connection.py  # WRDS connection setup and verification
├── tests/                   # Test suite
│   ├── conftest.py          # Shared fixtures
│   └── unit/                # Unit tests
├── data/                    # Data directory (not in git)
└── documentation/           # Release notes and docs

Questions

If you're unsure about something, open an issue to discuss before investing significant effort.