Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
241 lines (168 loc) · 7.49 KB

CONTRIBUTING.md

File metadata and controls

241 lines (168 loc) · 7.49 KB

Contributing to the OpenRouter AI SDK Provider

Thank you for your interest in contributing to the OpenRouter provider for the Vercel AI SDK! This guide will help you get started as a contributor.

Getting Started

Prerequisites

  • Node.js v18 or higher
  • pnpm v9.15.0 or higher (the project uses pnpm as its package manager)

Setting Up the Repository

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/YOUR-USERNAME/ai-sdk-provider.git
cd ai-sdk-provider

  3. Install dependencies:

    pnpm install

  4. Build the project:

    pnpm build

Development Workflow

Building

To build the package during development:

# Build once
pnpm build

# Build in watch mode for continuous development
pnpm dev

Code Style and Formatting

We use Biome for code linting and formatting. Before submitting a PR, make sure your code passes all checks:

# Check both linting and formatting
pnpm stylecheck

# Fix formatting issues automatically
pnpm format

# Run linting and formatting checks
pnpm stylecheck

Type Checking

Ensure your changes pass TypeScript type checking:

pnpm typecheck

Testing

The project includes tests for both Node.js and Edge environments. Make sure to run the tests before submitting a PR:

# Run all tests
pnpm test

# Run only Node.js tests
pnpm test:node

# Run only Edge environment tests
pnpm test:edge

Writing Tests

When adding new features or fixing bugs, please include tests. Test files follow the naming convention of *.test.ts and are located in the same directory as the files they test.

Examples of test files include:

  • openrouter-chat-language-model.test.ts
  • openrouter-usage-accounting.test.ts
  • openrouter-stream-usage-accounting.test.ts

Issue-Specific Regression Tests

When fixing bugs reported in GitHub issues, add a regression test to the e2e/issues/ directory. This ensures the issue doesn't recur and provides traceability back to the original report.

Running issue regression tests:

# Run issue regression tests separately (not included in test:e2e)
pnpm test:issues

Note: Issue regression tests are excluded from pnpm test:e2e because they may hit different models/APIs that could be slow or rate-limited. Run them separately when needed.

File naming convention: issue-{number}-{brief-description}.test.ts

Required test file structure:

/**
 * Regression test for GitHub issue #{number}
 * https://github.com/OpenRouterTeam/ai-sdk-provider/issues/{number}
 *
 * Reported error: {exact error message from the issue}
 * Model: {model ID if applicable}
 *
 * This test verifies that {what the test checks}.
 */
import { ... } from 'ai';
import { describe, expect, it, vi } from 'vitest';
import { createOpenRouter } from '@/src';

describe('Issue #{number}: {brief description}', () => {
  // Test cases that verify the issue is resolved
});

Note: Only include known facts from the issue report (error message, model, SDK version). Do not include speculative root cause analysis.

When to add issue regression tests:

  • Bug fixes that have a clear reproduction case
  • Issues that could potentially regress
  • API compatibility issues with specific models or features

When NOT to add issue regression tests:

  • Documentation-only changes
  • Issues that were user configuration errors
  • Transient API issues that were fixed server-side (though you may still add one for monitoring)

Adding New Features

When adding new features to the OpenRouter provider:

  1. Start by understanding the existing architecture in the src directory
  2. Update the relevant type definitions in types.ts if needed
  3. Implement the feature in the appropriate files
  4. Add tests to verify the functionality
  5. Update the README.md to document the new feature
  6. Update the CHANGELOG.md if applicable

Example: Usage Accounting Feature

The usage accounting feature provides an example of how to add features to the provider:

  1. Added types in types.ts for usage accounting
  2. Enhanced response schemas to include usage data
  3. Updated the implementation in openrouter-chat-language-model.ts
  4. Added tests in openrouter-usage-accounting.test.ts and openrouter-stream-usage-accounting.test.ts
  5. Updated README.md with usage examples

Pull Request Process

Important: All PRs that should trigger a release must include a changeset. Run pnpm changeset before submitting your PR.

  1. Create a new branch for your changes

  2. Make your changes, including tests and documentation updates

  3. Add a changeset to describe your changes:

    pnpm changeset

    This will prompt you to select the type of change (patch/minor/major) and write a summary. The changeset will be used to automatically generate release notes and bump versions.

    • patch: Bug fixes and small changes that don't affect the API
    • minor: New features that are backwards-compatible
    • major: Breaking changes

    If your changes don't need a release (docs, tests, CI config), create an empty changeset:

    pnpm changeset --empty

  4. Run all checks locally before submitting:

    pnpm stylecheck    # Check formatting
pnpm typecheck     # Check types
pnpm build         # Build the project
pnpm test          # Run all tests

  5. Fix any issues found by the checks (use pnpm format for formatting)

  6. Commit with clear, descriptive messages (including the changeset file)

  7. Push to your fork and submit a pull request

  8. Update the PR description with any relevant information

Note: Our CI will automatically run all these checks on your PR. PRs with failing checks cannot be merged.

PR Title Convention

Use a descriptive title that explains the change:

  • fix: <description> for bug fixes
  • feat: <description> for new features
  • docs: <description> for documentation changes
  • test: <description> for test changes
  • chore: <description> for maintenance tasks

Release Process

This project uses Changesets for automated release management.

How it works

  1. Contributors add changesets: When you submit a PR with changes that affect the public API or fix bugs, you include a changeset file (created with pnpm changeset) that describes your changes.

  2. Automated version PR: When PRs with changesets are merged to main, the Release workflow automatically creates or updates a "Version Packages" PR. This PR:

    • Bumps the version in package.json based on all pending changesets
    • Updates CHANGELOG.md with all changes since the last release
    • Removes the changeset files that have been processed

  3. Publish to npm: When a maintainer merges the "Version Packages" PR, the package is automatically published to npm with provenance.

For Maintainers

To release a new version:

  1. Review the automatically created "Version Packages" PR
  2. Verify the version bump is appropriate
  3. Verify the CHANGELOG entries are accurate
  4. Merge the PR
  5. The Release workflow will automatically publish to npm

Manual releases (emergency only)

In case of emergency, a manual release can be triggered using the legacy publish-manual.yaml workflow by creating a GitHub Release. This should only be used when the automated process is unavailable.

Getting Help

If you have questions about contributing, please open a GitHub issue in the repository.

Thank you for contributing to the OpenRouter AI SDK Provider!