Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
222 lines (164 loc) · 6.21 KB

CONTRIBUTING.md

File metadata and controls

222 lines (164 loc) · 6.21 KB

Contributing to Graphon

This guide reflects the repository's current local tooling and GitHub Actions checks.

By default, use make for routine development. Direct uv, ruff, pytest, and prek usage is still fine when you need a targeted command.

Development Setup

Requirements

  • Python 3.12 or 3.13
  • uv
  • make
  • git

Python 3.14 is currently unsupported because unstructured, which is used by the document extraction node, currently declares Requires-Python: <3.14.

Bootstrap

make dev
# optional for interactive work
source .venv/bin/activate

make dev will:

  • run uv sync
  • install prek Git hooks

The repository uses uv for dependency and virtual environment management. The default development environment includes ruff, pytest, pytest-xdist, pytest-cov, pytest-mock, and prek.

Git Hooks

make dev installs prek hooks from prek.toml.

The current hook set includes:

  • trailing whitespace and end-of-file cleanup
  • BOM cleanup and line ending normalization
  • TOML and YAML validation
  • shebang executable checks
  • local make format
  • local make lint

Useful direct commands:

uv run prek install
uv run prek run -a
uv run prek list
uv run prek validate-config

Use make by default. For targeted work, direct tool usage is still fine:

uv run ruff check src/graphon/path.py
uv run pytest tests/path/test_file.py -k keyword
uv run prek run -a

Testing and Validation

Use these commands for normal development:

  • make format: run uv run ruff format
  • make lint: run uv run ruff check --fix
  • make check: run uv run ruff format --check && uv run ruff check
  • make test: run uv run --frozen pytest
  • make pre: run format, lint, and test
  • make build: build the package distributions
  • make clean: remove build artifacts and caches

Notes:

  • make lint is mutating. It may rewrite files.
  • make check is the non-mutating style and lint check used in CI.
  • pytest is configured with -n auto and testpaths = ['tests'], so the test suite runs in parallel by default.
  • make test uses --frozen. If you change dependencies, refresh and commit uv.lock before opening a pull request.

For most changes, a good local sequence is:

make pre
make check

make pre applies local fixes and runs the test suite. make check then confirms the non-mutating CI check job will pass.

CI Checks

Pull requests targeting main currently run four kinds of checks:

  1. PR title validation with amannn/action-semantic-pull-request
  2. Commit history validation with cocogitto check
  3. make check
  4. make test on Python 3.12 and 3.13

Keep local workflow aligned with those checks. A green local make pre is useful, but it is not a complete substitute for the exact CI flow because CI also validates commit messages, PR titles, and a Python version matrix.

Git Commits

This repository enforces Conventional Commits for commit messages. The same format is required for pull request titles.

The PR title validator currently accepts these types:

  • feat
  • fix
  • docs
  • style
  • refactor
  • perf
  • test
  • build
  • ci
  • chore
  • revert

Rules:

  • use an optional scope when it improves clarity
  • mark breaking changes with !
  • remember that the pull request title becomes the squash merge commit message
  • keep the entire commit history reviewable, because CI validates all commits in the pull request

Examples:

feat: add graph snapshot export
fix(runtime): avoid duplicate node completion events
docs(contributing): clarify CI workflow
refactor(api)!: remove deprecated runtime entrypoint

Issues

Before you start implementation or open a new issue, search the existing open and closed issues and pull requests to confirm the work is not already tracked or in progress.

Rules:

  • do not open duplicate issues or parallel pull requests for the same change
  • if related work already exists, continue that discussion instead of starting a new thread
  • if no issue exists for the change, create one before opening a pull request
  • if GitHub presents an issue template or issue form, fill out every required field and keep the provided structure intact

Pull Requests

Every pull request must be linked to an issue. Use a closing or reference keyword such as Closes #123, Fixes #123, or Refs #123 in the pull request body.

Before you open a pull request:

  • search existing pull requests again to confirm there is no duplicate review in progress
  • make sure the change stays focused and reviewable
  • run make pre before pushing and keep make check green locally when possible

When you open a pull request:

  • use a Conventional Commits title, and mark breaking changes with !, because the pull request title becomes the squash merge commit message
  • link the related issue in the pull request body
  • follow .github/pull_request_template.md exactly
  • do not delete required headings or checklist items from the template; if a section is not applicable, say so explicitly
  • if CLA Assistant prompts you, sign CLA.md in the pull request conversation before merge
  • add or update tests for behavior changes unless the change genuinely does not require them
  • update contributor-facing or user-facing documentation when needed

CLA

If CLA Assistant asks you to sign the repository CLA, read CLA.md and post this exact comment once in the pull request conversation:

I have read the CLA Document and I hereby sign the CLA

The CLA workflow is separate from the normal PR checks.

Maintainer Notes

Version bumps and changelog updates are managed with uv version and cog:

make bump SEM=patch
make bump SEM=minor
make bump SEM=major

Release tags use the v prefix and are intended to be created from main.

CLA signatures are stored on the dedicated cla-signatures branch. Maintainers must keep that branch available and writable to GitHub Actions.