Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
153 lines (106 loc) · 4.92 KB

CONTRIBUTING.md

File metadata and controls

153 lines (106 loc) · 4.92 KB
Raw

Contributing to CAMB

Thank you for your interest in contributing to CAMB! This guide will help you set up your development environment and understand our code standards.

Development Setup

1. Clone and Install

git clone --recursive https://github.com/cmbant/CAMB.git
cd CAMB
pip install -e .[dev]

2. Install Pre-commit Hooks

git config core.hooksPath .githooks

The repository ships a portable .githooks/pre-commit wrapper that looks for pre-commit in the CAMB devcontainer environment first, then in the current checkout's .venv, then in the main checkout's .venv when you are committing from a linked worktree, then on your PATH. This keeps the same checkout working on a Linux devcontainer and a Windows host without rewriting the hook each time you switch environments.

3. Code Formatting Standards

CAMB uses Ruff for Python formatting and linting:

  • Line length: 120 characters
  • Quote style: Double quotes
  • Python version: 3.10+
  • Import sorting: Automatic via ruff
  • Target version: py310

The pre-commit hooks include:

  • Ruff formatting and linting (Python files)
  • forformat for Fortran formatting, using the [tool.forformat] settings in pyproject.toml
  • Trailing whitespace removal (Python, Fortran, Jupyter notebooks)
  • End-of-file fixing (Python, Fortran, Jupyter notebooks)
  • PyUpgrade for Python 3.10+ syntax

The Fortran hook comes from the forformat-pre-commit hook repository, installs the published forformat wheel, operates on the Fortran files selected by pre-commit, and excludes the forutils submodule. forformat uses the surrounding Git checkout to resolve declarations while modifying only the selected files.

4. Before Committing

The pre-commit hooks will run automatically, but you can also run them manually:

# Run all pre-commit hooks
pre-commit run --all-files

# Run the Fortran hooks on selected files
pre-commit run forformat fortran/path.f90

# Run only ruff formatting
pre-commit run ruff-format --files camb fortran/tests

# Run only ruff linting with fixes
pre-commit run ruff-check --files camb fortran/tests

Testing

Run the test suite to ensure your changes don't break anything:

python -m unittest camb.tests.camb_test

To run the full suite including the slower symbolic and emission-angle tests:

python -m unittest camb.tests.camb_test camb.tests.camb_test_slow

The GitHub workflows include camb.tests.camb_test_slow by default, and skip it when CAMB_TEST_FAST is set.

For HMcode tests (Linux only):

git clone https://github.com/alexander-mead/HMcode_test_outputs.git
python -m unittest camb.tests.hmcode_test

VS Code Setup

The repository includes VS Code configuration files with:

  • Recommended extensions: Python, Ruff, Fortran linter
  • Format on save: Enabled with Ruff as the default Python formatter
  • Rulers at 120 characters
  • Pylance settings: Configured to silence most NumPy-related type errors
  • Fortran formatting: Configured with forformat in pyproject.toml; the same settings are used by the forformat pre-commit hook
  • Fortran project context: The Modern Fortran adapter passes the workspace folder to forformat so it can find the checkout and its pyproject.toml

Recommended Extensions

The following extensions will be suggested when you open the project:

  • ms-python.python - Python support
  • ms-python.debugpy - Python debugging
  • charliermarsh.ruff - Ruff formatter and linter
  • fortran-lang.linter-gfortran - Fortran support

The committed workspace settings only help VS Code discover a local ./.venv; the devcontainer sets its container-local interpreter separately, so host and container environments do not fight each other.

Optional Fortran Tools

For enhanced Fortran development, you may want to install:

pip install forformat fortls

Note: You may need to configure global VS Code settings for Fortran tool paths.

Pull Request Guidelines

  1. Install pre-commit hooks before making changes
  2. Test your changes locally
  3. Write clear commit messages
  4. Keep PRs focused on a single feature or fix
  5. Update documentation if needed
  6. Ensure CI passes - GitHub Actions will check formatting and run tests

Questions?

For AI Agents

If you're an AI agent contributing code, follow these guidelines:

1. Use Standard Ruff/Pre-commit Settings

2. Clear Attribution in PRs

  • Use author name "AI agent" when creating PRs
  • Include clear commit messages indicating AI authorship: 
    git commit -m "Fix issue XYZ (AI agent)"