> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/graphprotocol/graph-node/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  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.
</Note>

Join the conversation on [Discord](https://discord.gg/graphprotocol) and follow the [Code of Conduct](https://github.com/graphprotocol/graph-node/blob/master/CODE_OF_CONDUCT.md) for all communications.

## Getting Started

Check out [these good first issues](https://github.com/graphprotocol/graph-node/labels/good%20first%20issue) to find beginner-friendly tasks.

## Development Setup

<Steps>
  <Step title="Install Development Tools">
    Install the required Rust development helpers:

    ```bash theme={null}
    cargo install cargo-watch
    rustup component add rustfmt
    ```
  </Step>

  <Step title="Configure Environment Variables">
    Set up the required environment variables for testing:

    ```bash theme={null}
    # Required for Diesel/Postgres store testing
    export THEGRAPH_STORE_POSTGRES_DIESEL_URL=postgresql://graph:graph@127.0.0.1:5432/graph-test
    ```

    <Note>
      You can follow the Docker Compose instructions in `store/test-store/README.md` to easily run a Postgres instance.
    </Note>
  </Step>

  <Step title="Run Development Watcher">
    While developing, run this command in the background to automatically format, check, test, and document your code:

    ```bash theme={null}
    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
  </Step>
</Steps>

## Code Quality Requirements

<Warning>
  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
</Warning>

### Mandatory Pre-Commit Checks

<CodeGroup>
  ```bash Format Code theme={null}
  # 🚨 MANDATORY: Format all code after any .rs file edit
  just format
  ```

  ```bash Lint Code theme={null}
  # 🚨 MANDATORY: Check for warnings and errors
  just lint
  ```

  ```bash Check Release Build theme={null}
  # 🚨 MANDATORY: Catch linking/optimization issues
  just check --release
  ```

  ```bash Run Tests theme={null}
  # 🚨 MANDATORY: Ensure tests pass
  just test-unit
  ```
</CodeGroup>

## 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.

<Warning>
  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.
</Warning>

## Commit Message Format

We use a specific format for commit messages to maintain consistency:

```
{crate-name}: {Brief description of changes}
```

### Examples

<CodeGroup>
  ```text Single Crate theme={null}
  store: Support 'Or' filters
  ```

  ```text Multiple Crates theme={null}
  core, graphql: Add event source to store
  ```

  ```text All Crates theme={null}
  all: Update dependencies to latest versions
  ```
</CodeGroup>

### 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"

<Note>
  Use `git rebase -i` frequently to restructure your commits into logical, atomic steps.
</Note>

## 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

<Steps>
  <Step title="Rebase on Master">
    Do NOT merge master into your branch. Instead, rebase your branch on top of the latest master:

    ```bash theme={null}
    git fetch origin
    git rebase origin/master
    ```
  </Step>

  <Step title="Keep History Linear">
    We try to keep the history of the `master` branch linear and avoid merge commits.
  </Step>

  <Step title="Merge After Approval">
    Once your pull request is approved, merge it using these steps:

    ```bash theme={null}
    git checkout master
    git pull master
    git rebase master my/branch
    git push -f
    git checkout master
    git merge my/branch
    git push
    ```

    <Note>
      Alternatively, clicking the "Rebase and merge" button in the GitHub UI has the same effect.
    </Note>
  </Step>
</Steps>

## Development Workflow

### Using Process Compose (Recommended)

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

<CodeGroup>
  ```bash Unit Tests theme={null}
  # Start PostgreSQL + IPFS for unit tests
  nix run .#unit

  # In another terminal, run tests
  just test-unit
  ```

  ```bash Runner Tests theme={null}
  # Start PostgreSQL + IPFS for runner tests
  nix run .#unit

  # In another terminal, run tests
  just test-runner
  ```

  ```bash Integration Tests theme={null}
  # Start all services (PostgreSQL, IPFS, Anvil)
  nix run .#integration

  # In another terminal, run tests
  just test-integration
  ```
</CodeGroup>

### 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](https://discord.gg/graphprotocol)
* For bugs or feature requests: Create a [GitHub issue](https://github.com/graphprotocol/graph-node/issues)
* For complex changes: Discuss first in GitHub Issues or Discord

## Resources

* [Good First Issues](https://github.com/graphprotocol/graph-node/labels/good%20first%20issue)
* [Code of Conduct](https://github.com/graphprotocol/graph-node/blob/master/CODE_OF_CONDUCT.md)
* [Discord Community](https://discord.gg/graphprotocol)
* [Official Documentation](https://thegraph.com/docs/)