Skip to content

Latest commit

 

History

History
178 lines (116 loc) · 7.18 KB

CONTRIBUTING.md

File metadata and controls

178 lines (116 loc) · 7.18 KB

Contributing

Thanks for your interest in contributing to Ponder! Please take a moment to review this document before submitting a pull request.

If you want to contribute, but aren't sure where to start, reach out in Ponder's public telegram group or create a new discussion.

Get started

This guide is intended to help you get started with contributing. By following these steps, you will understand the development process and workflow.



Fork the repository

To start contributing to the project, use the GitHub CLI to create a fork and clone it to your local machine:

gh repo fork 0xOlias/ponder --clone

Or, manually create a fork using the button at the top of the repo on GitHub, then clone it to your local machine using git clone {your-fork-url}.

Install Node.js and pnpm

Ponder uses pnpm workspaces to manage multiple projects. You need to install Node.js v16 or higher and pnpm v7 or higher.

You can run the following commands in your terminal to check your local Node.js and pnpm versions:

node -v
pnpm -v

If the versions are not correct or you don't have Node.js or pnpm installed, download and follow their setup instructions:

Install Foundry

Ponder uses Foundry for testing. The test suite uses local Anvil instances via Anvil.js to run isolated, concurrent tests against forks of Ethereum mainnet.

Install Foundry (and Anvil) using the following command:

curl -L https://foundry.paradigm.xyz | bash

Install dependencies

In the project's root directory, run the following command to install the project's dependencies:

pnpm install

After the install completes, pnpm links packages across the project for development. This means that if you run any of the projects in the examples/ directory, they will use the local version of @ponder/core.

Run the test suite

Environment variables

The test suite uses mainnet forking to test against real-world data. To get this working, you'll need to set up environment variables.

First, create a env.local file using the provided template.

cp .env.example .env.local
  • ANVIL_FORK_URL must be a mainnet RPC URL from a service provider like Alchemy.
  • DATABASE_URL (optional) is a connection string to a Postgres database. If DATABASE_URL is provided, the test suite will run against the specified Postgres database. If not, tests will run against an in-memory SQLite database. Unless you are specifically testing Postgres behavior, you don't need to run tests against Postgres locally and can instead rely on CI to catch any regressions.

Running tests

The test suite uses vitest in concurrent mode as a test runner.

Herea are some commands to get you started.

  • pnpm build - required for a fresh install
  • pnpm test — run all tests in watch mode
  • pnpm test path/to/file.test.ts — run a single test file
  • pnpm test path/to/dir — run all test files in a directory

When adding new features or fixing bugs, it's important to add test cases to cover any new or updated behavior.

Write documentation

Ponder uses Nextra and Markdown for the documentation website (located at docs). To start the docs website in dev mode, run:

cd docs && pnpm dev

Submit a pull request

When you're ready to submit a pull request, follow these naming conventions:

  • Pull request titles use the imperative mood (e.g., Add something, Fix something).
  • Changesets use past tense verbs (e.g., Added something, Fixed something).

When you submit a pull request, a GitHub Action will automatically lint, build, and test your changes. If you see an ❌, it's most likely a problem with your code. Inspect the logs through the GitHub Actions UI to find the cause.

Versioning and releases

Ponder uses changesets to manage package versioning and NPM releases.

Ponder is still in alpha, so all changes should be marked as a patch.

Changesets workflow

  1. Write a PR that includes a public API change or bug fix.
  2. Create a changeset using pnpm changeset. The changesets CLI will ask you which package is affected (@ponder/core or create-ponder) and if the change is a patch, minor, or major release.
  3. The changesets CLI will generate a Markdown file in .changeset/ that includes the details you provided. Commit this file to your PR branch (e.g. git commit -m "chore: changeset").
  4. When you push this commit to remote, a GitHub bot will detect the changeset and add a comment to your PR with a preview of the changelog.
  5. Merge your PR. The changesets Github Action workflow will open (or update) a PR with the title "chore: version packages". The changes in your PR will not be released until this PR is merged.

Releases

When you're ready to release, merge the "chore: version packages" PR into main. This will trigger the changesets Github Action workflow to build packages, publish to NPM, and create a new GitHub release.

That's it!

If you still have questions, please reach out in Ponder's public telegram group or create a new discussion.

This guide was adapted from viem's contribution guide. ❤️