Skip to content

Contributing to GraFlo

We welcome contributions to GraFlo! This document provides guidelines and instructions for contributing to the project.

Licensing your contribution

GraFlo is released under the Apache License 2.0. Before we can merge your first pull request, you need to accept the Growgraph Contributor License Agreement (CLA). You do it once, and it covers all your future contributions to Growgraph projects. You keep the copyright in your work, and everything you contribute stays available under an open source license.

When you open a pull request, a bot checks whether you have accepted the CLA. If you have not, it comments with a link. Read the agreement and reply on the pull request with:

I have read the Growgraph CLA and I accept it.

The cla check then turns green. You can also sign the agreement on paper: see its section 11.

Contributing as part of your job? Contributions written at work are welcome. Many employers own what their employees write, though, so before you contribute, either get your employer's permission or ask them to sign our Corporate CLA (write to team@growgraph.dev). If you are not sure whether your employer has a claim, ask them first.

Do not submit code you did not write without telling us its source and license.

Every commit must be authored with an e-mail address linked to your GitHub account; otherwise the check cannot match the commit to your acceptance.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. From the repository root (where pyproject.toml lives), install development dependencies: 
    uv sync --extra dev --extra plot
    The ty pre-commit hook type-checks graflo/plot, which imports the plot extra. Add --extra docs in the same command if you will build the documentation site locally: uv sync removes the extras you leave out.
  4. Install pre-commit hooks: 
    uv run pre-commit install

Development Workflow

  1. Create a new branch for your feature or bugfix: 

    git checkout -b feature/your-feature-name

  2. Make your changes and ensure tests pass: 

    uv run pytest test

  3. Commit your changes with a descriptive message: 

    git commit -m "Add feature: your feature description"

  4. Push your branch to your fork: 

    git push origin feature/your-feature-name

  5. Create a Pull Request on GitHub

Code Style

  • Follow PEP 8 style guidelines
  • Use type hints for all function parameters and return values
  • Write docstrings following the Google style
  • Keep functions focused and small
  • Add tests for new features

Documentation

  • Update relevant documentation when adding new features
  • Add docstrings to all new functions and classes
  • Include examples in docstrings where appropriate
  • Update the changelog for significant changes

To build and preview the docs site locally:

uv sync --extra dev --extra plot --extra docs
uv run properdocs serve

If you edit the GraFlo meta-ontology (graflo/rdf/ontology/graflo.ttl), regenerate the interactive visualization and commit the updated assets:

uv run python docs/_build/scripts/build_ontology_viz.py

Visual tweaks and the graph viewer live in repo-owned files under docs/_build/scripts/ontology_viz/ and are copied into docs/assets/graflo-ontology-viz/ at build time. Do not edit packages inside .venv.

CI runs the same script and fails if docs/assets/graflo-ontology-viz/ is out of date with the committed ontology.

Testing

  • Write tests for all new features
  • Ensure all tests pass before submitting a PR
  • Add tests for bug fixes
  • Maintain or improve test coverage

Test databases

Most of the suite needs live database containers. From a clone, start them with the scripts under docker/:

cd docker
./start-all.sh    # Start all services
./stop-all.sh     # Stop all services
./cleanup-all.sh  # Remove containers and volumes

Per-engine compose files, ports, and env notes are in docker/README.md. Then run:

uv run pytest test

Tests marked tigergraph, nebula, kafka or performance are skipped unless you pass the matching option: --run-tigergraph, --run-nebula, --run-kafka or --run-performance.

The suites under test/db need the containers. The rest runs in-process — the live parts of test/data_source and test/object_storage skip when their service is unreachable — and CI runs exactly that part on every pull request:

uv run pytest test --ignore=test/db -n auto --dist loadfile

CI does not run test/db, so run it locally before a change to a backend. A weekly workflow runs the same suites against the newest dependency versions pyproject.toml admits, rather than the ones uv.lock pins. Unit tests of backend code that need no database go in test/backends/, where CI runs them.

Property tests (Hypothesis) run under the ci profile by default: a fifth of each test's example count, derandomized. Run them at the full count with HYPOTHESIS_PROFILE=full (or --hypothesis-profile=full). A test that sets its own count writes it through examples() in test/hypothesis_budget.py, so the profile still scales it.

uv version

pyproject.toml sets required-version for uv, and the workflows pin the same line. A different uv minor rewrites uv.lock with identical content, so change both together.

Compatibility

GraFlo follows Semantic Versioning. Within a major version, public names and manifest keys are not removed or renamed without a deprecation first:

  • Deprecate in a minor release with graflo._compat: @deprecated(since=..., removed_in=..., use=...) on a callable, rename_key(...) in a mode="before" validator for a renamed config key. Remove in the next major.
  • .github/scripts/api_breaks.py compares the public API with the newest release tag and fails on a break unless pyproject.toml already declares a new major version. It is not run in CI for now.
  • A change to a contract field's default moves content hashes: bump CANON_VERSION as well (see Versioning).

Pull Request Process

  1. Ensure your PR description clearly describes the problem and solution
  2. Include relevant tests
  3. Update documentation as needed
  4. Ensure all CI checks pass
  5. Request review from maintainers

Reporting Issues

When reporting issues, please include:

  • Python version
  • GraFlo version
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Any relevant error messages