Contributing to Graph Node

Guidelines for contributing code, commits, and pull requests to Graph Node

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

Format Code

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

# 🚨 MANDATORY: Check for warnings and errors
just lint

# 🚨 MANDATORY: Catch linking/optimization issues
just check --release

# 🚨 MANDATORY: Ensure tests pass
just test-unit

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

Single Crate

store: Support 'Or' filters

core, graphql: Add event source to store

all: Update dependencies to latest versions

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

Using Process Compose (Recommended)

The repository includes a process-compose-flake setup for native service management:

Unit Tests

# Start PostgreSQL + IPFS for unit tests
nix run .#unit

# In another terminal, run tests
just test-unit

# Start PostgreSQL + IPFS for runner tests
nix run .#unit

# In another terminal, run tests
just test-runner

# Start all services (PostgreSQL, IPFS, Anvil)
nix run .#integration

# In another terminal, run tests
just test-integration

Service Configuration

Service	Unit Tests Port	Integration Tests Port	Database/Config
PostgreSQL	5432	3011	graph-test / graph-node
IPFS	5001	3001	Data in ./.data/unit or ./.data/integration
Anvil (Ethereum)	-	3021	Deterministic 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

• Good First Issues
• Code of Conduct
• Discord Community
• Official Documentation