Skip to content

Contributing

Thank you for your interest in contributing to ResearchPad. This guide covers the development setup, build process, and pull request workflow.

Development Setup

Prerequisites

  • Python >= 3.10
  • Node.js >= 18
  • npm >= 9

Clone and Install

git clone https://github.com/researchpad/researchpad.git
cd researchpad
make install

This runs pip install -e ".[dev,docs]", which installs the package in editable mode along with development and documentation dependencies.

Start Development Servers

make dev

This starts both the frontend dev server (with hot reload) and the backend server concurrently.

Project Structure

researchpad/
  src/
    frontend/       # React + Tailwind UI
    server/         # Node.js API server
  researchpad/
    cli/            # Python CLI (init, runserver, version)
    server/         # Bundled server (generated by build)
    templates/      # Cursor command templates
  tests/            # Python test suite
  docs/             # Documentation (mkdocs)

Building

make build

This builds both the frontend and server into production bundles at researchpad/server/. The build process:

  1. Runs npm ci && npm run build in src/frontend/
  2. Runs npm ci && node build.mjs in src/server/

Running Tests

make test

This runs the Python test suite with pytest:

pytest tests/ -v

Serving Docs Locally

make docs

This starts a local mkdocs development server at http://localhost:8000 with live reload.

Pull Request Process

  1. Fork the repository and create a feature branch from main.
  2. Make your changes. Keep commits focused and write clear commit messages.
  3. Add tests for any new functionality.
  4. Run the test suite to confirm nothing is broken: make test
  5. Open a pull request against main with a clear description of what changed and why.

Code style

The project uses Ruff for Python linting and formatting. The configuration lives in pyproject.toml with a line length of 100 and a target version of Python 3.10.

Reporting Issues

Open an issue on GitHub with:

  • A clear title and description
  • Steps to reproduce (if applicable)
  • Expected vs. actual behavior
  • Your Python version, Node.js version, and operating system