Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
131 lines (91 loc) · 4.38 KB

CONTRIBUTING.md

File metadata and controls

131 lines (91 loc) · 4.38 KB
Raw

Contributing to Open-Inspect

Thank you for your interest in contributing to Open-Inspect! This document provides guidelines for contributing to the project.

Getting Started

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/YOUR-USERNAME/background-agents.git
  3. Run the setup script: bash .openinspect/setup.sh
  4. Create a branch for your changes: git checkout -b feature/your-feature-name

Development Setup

The quickest way to get a working environment:

bash .openinspect/setup.sh

This handles npm dependencies, builds the shared package, configures git hooks (husky + lint-staged), and optionally sets up a Python virtualenv for packages/modal-infra.

See docs/GETTING_STARTED.md for full deployment instructions. See docs/SETUP_GUIDE.md for local setup and day-to-day development paths. To run OpenCode itself on a checkout of this repo, see docs/OPENCODE_LOCAL.md.

For manual setup or individual steps:

# Install dependencies
npm install

# Build shared package
npm run build -w @open-inspect/shared

# Run type checking
npm run typecheck

# Run linting
npm run lint

# Run tests
npm test

Project Structure

Package Description
packages/control-plane Cloudflare Workers + Durable Objects
packages/web Next.js web application
packages/sandbox-runtime Shared in-sandbox agent runtime
packages/modal-infra Modal sandbox infrastructure
packages/daytona-infra Daytona snapshot infrastructure
packages/shared Shared types and utilities

Making Changes

Code Style

  • Run npm run lint before committing
  • Run npm run typecheck to ensure type safety
  • Follow existing code patterns in the codebase

Test Performance

Run heavyweight validation commands (lint, typecheck, and full test suites) sequentially on a shared development host. Each Vitest invocation sizes its own worker pool independently; running multiple full suites together can exhaust a test's elapsed-time budget even when its assertions are correct. If you intentionally overlap suites, pass an explicit --maxWorkers budget to each invocation, accounting for the other work on the host.

In DOM tests, scope queries to the relevant form section or open listbox. For example, within(screen.getByRole("listbox")).getByRole("option", { name }) avoids scanning unrelated options, including Radix's hidden native selects, while preserving accessibility checks. Prefer label queries when selecting labeled inputs. Investigate slow operations before increasing test timeouts or adding retries.

For coverage commands, the recorded baseline, and test-reduction tradeoffs, see Coverage-Guided Test Reduction. Control-plane coverage combines the Node and workerd suites; unit-only coverage is not the measure of retained integration coverage. The unfiltered Coverage workflow enforces production-only TypeScript and separate Python statement/branch floors. Repository administrators should require its Coverage check in main rules.

Commit Messages

Use clear, descriptive commit messages:

  • feat: add new feature
  • fix: resolve issue with X
  • docs: update documentation
  • refactor: restructure module

Pull Requests

  1. Ensure all tests pass: npm test
  2. Ensure linting passes: npm run lint
  3. Ensure type checking passes: npm run typecheck
  4. Update documentation if needed
  5. Provide a clear description of your changes

Database Changes

SQL in the control plane must stay inside the portable subset — see docs/PORTABLE_SQL.md. npm run lint:sql-portability checks it.

Source Control Provider Contributions

For SCM/provider changes, follow:

  • docs/adr/0001-single-provider-scm-boundaries.md
  • docs/provider-contribution-checklist.md

Reporting Issues

When reporting issues, please include:

  • A clear description of the problem
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, Node version, etc.)

Questions

If you have questions, please open a GitHub issue with the "question" label.

License

By contributing, you agree that your contributions will be licensed under the MIT License.