Skip to main content
Welcome to the Graph Protocol! We appreciate your interest in contributing to Graph Node.
If you run into any problems, feel free to create an issue. For simple fixes, PRs are much appreciated. For complex changes, we’d appreciate having a quick chat in GitHub Issues or Discord first.
Join the conversation on Discord and follow the Code of Conduct for all communications.

​
Getting Started

Check out these good first issues to find beginner-friendly tasks.

​
Development Setup

1

Install Development Tools

Install the required Rust development helpers:
cargo install cargo-watch
rustup component add rustfmt
2

Configure Environment Variables

Set up the required environment variables for testing:
# Required for Diesel/Postgres store testing
export THEGRAPH_STORE_POSTGRES_DIESEL_URL=postgresql://graph:graph@127.0.0.1:5432/graph-test
You can follow the Docker Compose instructions in store/test-store/README.md to easily run a Postgres instance.
3

Run Development Watcher

While developing, run this command in the background to automatically format, check, test, and document your code:
cargo watch \
    -x "fmt --all" \
    -x check \
    -x "test -- --test-threads=1" \
    -x "doc --no-deps"
This will continuously:
  • Build all packages in target/
  • Generate docs in target/doc/
  • Automatically format your source files

​
Code Quality Requirements

Before ANY commit or PR, ALL of the following MUST be satisfied:
  • cargo fmt --all MUST be run
  • just lint MUST show zero warnings
  • cargo check --release MUST complete successfully
  • Unit test suite MUST pass

​
Mandatory Pre-Commit Checks

# 🚨 MANDATORY: Format all code after any .rs file edit
just format

​
Testing Guidelines

​
Integration Tests

Tests can and should be run against a sharded store. See store/test-store/README.md for detailed instructions on running sharded integration tests.
Only run integration tests when explicitly needed:
  • Making changes to integration/end-to-end functionality
  • Debugging issues requiring full system testing
  • Preparing releases or major changes
Use unit tests for regular development.

​
Commit Message Format

We use a specific format for commit messages to maintain consistency: 
{crate-name}: {Brief description of changes}

​
Examples

store: Support 'Or' filters

​
Commit Message Guidelines

  • Keep the body terse with just enough information to explain what the commit does
  • Extensive explanations of how the commit works are better as code comments
  • Each commit should be a small logical step towards the overall goal
  • Separate mechanical changes (like renaming) from logic changes
  • Don’t structure commits based on how you implemented the feature
  • Avoid commit messages like “Fix problem” or “Cleanup”
Use git rebase -i frequently to restructure your commits into logical, atomic steps.

​
Pull Request Guidelines

​
Commit Structure

Structure commits in your pull request so that:
  • Each commit consists of a small logical step
  • The PR makes it easy for reviewers to follow your changes
  • Simple mechanical changes are separated from logic changes
  • Commits tell the story of what was implemented, not how you debugged it

​
Git Workflow

1

Rebase on Master

Do NOT merge master into your branch. Instead, rebase your branch on top of the latest master:
git fetch origin
git rebase origin/master
2

Keep History Linear

We try to keep the history of the master branch linear and avoid merge commits.
3

Merge After Approval

Once your pull request is approved, merge it using these steps:
git checkout master
git pull master
git rebase master my/branch
git push -f
git checkout master
git merge my/branch
git push
Alternatively, clicking the “Rebase and merge” button in the GitHub UI has the same effect.

​
Development Workflow

The repository includes a process-compose-flake setup for native service management: 
# Start PostgreSQL + IPFS for unit tests
nix run .#unit

# In another terminal, run tests
just test-unit

​
Service Configuration

ServiceUnit Tests PortIntegration Tests PortDatabase/Config
PostgreSQL54323011graph-test / graph-node
IPFS50013001Data in ./.data/unit or ./.data/integration
Anvil (Ethereum)-3021Deterministic test chain

​
Communication

  • For questions or help: Join our Discord
  • For bugs or feature requests: Create a GitHub issue
  • For complex changes: Discuss first in GitHub Issues or Discord

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us