diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..788f9d0bb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,522 @@ +# Contributing to Echo + +Thank you for your interest in contributing to Echo! We're building user-pays AI infrastructure that helps developers monetize their AI applications without fronting costs. Every contribution helps make AI development more accessible and sustainable. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Bounties](#bounties) +- [Ways to Contribute](#ways-to-contribute) +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Project Structure](#project-structure) +- [Coding Standards](#coding-standards) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Pull Request Process](#pull-request-process) +- [Testing](#testing) +- [Documentation](#documentation) +- [Community and Support](#community-and-support) + +## Code of Conduct + +By participating in this project, you agree to be respectful, inclusive, and constructive. We aim to create a welcoming environment for all contributors regardless of background or experience level. + +## Bounties + +**Get paid to contribute to Echo!** + +We offer bounties for specific features, bug fixes, and improvements. This is a great way to get started with open source contributions while earning rewards for your work. + +[**View available bounties →**](https://terminal.merit.systems/Merit-Systems/echo/bounties) + +To claim a bounty: + +1. Check the [bounties page](https://terminal.merit.systems/Merit-Systems/echo/bounties) for available tasks +2. Comment on the bounty to express interest +3. Submit your work via pull request +4. Receive payment once your PR is merged + +New bounties are added regularly, so check back often! + +## Ways to Contribute + +### 🐛 Report Bugs + +If you find a bug, please [open an issue](https://github.com/Merit-Systems/echo/issues/new) with: + +- A clear, descriptive title +- Steps to reproduce the issue +- Expected vs. actual behavior +- Your environment (OS, Node version, browser, etc.) +- Screenshots or code snippets if applicable + +### 💡 Suggest Features + +Have an idea? We'd love to hear it! [Open a feature request](https://github.com/Merit-Systems/echo/issues/new) with: + +- A clear description of the feature +- Use cases and examples +- Why this would benefit Echo users +- Any implementation ideas you might have + +### 📝 Improve Documentation + +Documentation improvements are always welcome! This includes: + +- Fixing typos or unclear explanations +- Adding examples or tutorials +- Improving API documentation +- Translating documentation + +### 🔧 Submit Code Changes + +Ready to code? Check our [open issues](https://github.com/Merit-Systems/echo/issues) for ideas, or propose your own changes. + +## Getting Started + +### Prerequisites + +- **Node.js**: 18.0.0 or higher +- **pnpm**: 10.0.0 or higher +- **PostgreSQL**: Required for running Echo Control locally +- **Git**: For version control + +### Initial Setup + +1. **Fork and clone the repository** + + ```bash + git clone https://github.com/YOUR_USERNAME/echo.git + cd echo + ``` + +2. **Install dependencies** + + ```bash + pnpm install + ``` + +3. **Set up environment variables** + + ```bash + pnpm local-setup + ``` + +4. **Set up the database** (for Echo Control) + + ```bash + cd packages/app/control + ./setup-db.sh + # Or manually: + npx prisma generate + npx prisma db push + ``` + +5. **Start development servers** + + From the root directory: + + ```bash + pnpm dev + ``` + + This starts both Echo Control (localhost:3000) and Echo Server simultaneously. + +## Development Workflow + +### Creating a Branch + +Use descriptive branch names with prefixes: + +```bash +git checkout -b feature/add-anthropic-support +git checkout -b fix/balance-calculation-error +git checkout -b docs/improve-quickstart +git checkout -b refactor/simplify-auth-flow +``` + +### Making Changes + +1. Make your changes in focused, logical commits +2. Write or update tests for your changes +3. Ensure all tests pass: `pnpm test:all` +4. Run linting: `pnpm lint` +5. Check types: `pnpm type-check` +6. Format code: `pnpm format` + +### Testing Your Changes + +```bash +# Run all tests +pnpm test:all + +# Run unit tests only +pnpm test:unit + +# Run integration tests +pnpm test:integration + +# Test in a specific package +pnpm --filter @merit-systems/echo-react-sdk test +``` + +## Project Structure + +Echo is a monorepo organized as follows: + +``` +echo/ +├── packages/ +│ ├── app/ +│ │ ├── control/ # Echo Control Plane (Next.js app) +│ │ └── server/ # Echo Server (Express proxy) +│ ├── sdk/ +│ │ ├── ts/ # Core TypeScript SDK +│ │ ├── react/ # React SDK +│ │ ├── next/ # Next.js SDK +│ │ ├── aix402/ # AI SDK 402 payment protocol +│ │ └── auth-js-provider/# Auth.js provider +│ └── tests/ # Integration and smoke tests +├── templates/ # Starter templates +└── docs/ # Documentation +``` + +### Key Packages + +- **Echo Control** (`packages/app/control`): User-facing dashboard, authentication, billing +- **Echo Server** (`packages/app/server`): Proxy server for LLM requests with metering +- **Echo TS SDK** (`packages/sdk/ts`): Foundation for all framework-specific SDKs +- **Echo React SDK** (`packages/sdk/react`): React hooks and components +- **Echo Next SDK** (`packages/sdk/next`): Next.js App Router integration + +## Coding Standards + +### TypeScript + +- Use TypeScript for all new code +- Prefer explicit types over `any` +- Use interfaces for public APIs, types for internal structures +- Enable strict mode in `tsconfig.json` + +### Imports + +- **Always use absolute imports** with the `@` syntax, not relative imports +- Use kebab-case for TypeScript files +- Group imports: external packages → internal packages → local files + +```typescript +// ✅ Good +import { useState } from 'react'; +import { generateText } from 'ai'; + +import { useEchoAuth } from '@/hooks/use-echo-auth'; +import { Button } from '@/components/button'; + +// ❌ Bad +import { Button } from '../../../components/button'; +``` + +### React Components + +- Use functional components with hooks +- Prefer named exports for components +- Use TypeScript for prop types +- Follow kebab-case for component filenames + +```typescript +// user-avatar.tsx +export function UserAvatar({ user }: UserAvatarProps) { + // Implementation +} +``` + +### Naming Conventions + +- **Files**: kebab-case (`user-profile.tsx`, `api-client.ts`) +- **Components**: PascalCase (`UserProfile`, `ApiKeyList`) +- **Functions/Variables**: camelCase (`getUserBalance`, `apiKey`) +- **Constants**: SCREAMING_SNAKE_CASE (`API_KEY_PREFIX`, `MAX_RETRIES`) +- **Types/Interfaces**: PascalCase (`UserProfile`, `ApiResponse`) + +### Feature Flags + +When working with feature flags: + +- Use as few places as possible to reduce undefined behavior +- Store flag names in an enum (TypeScript) or const object (JavaScript) +- Use SCREAMING_SNAKE_CASE for flag names +- Gate flag-dependent code with validation checks + +```typescript +// ✅ Good +enum FeatureFlags { + ANTHROPIC_SUPPORT = 'anthropic_support', + USAGE_ANALYTICS = 'usage_analytics', +} + +if (flags[FeatureFlags.ANTHROPIC_SUPPORT] === true) { + // Feature-specific code +} +``` + +### Custom Properties (Analytics) + +- Store event/property names in enums or const objects when used in 2+ places +- Follow existing naming conventions (consult maintainers if unsure) +- Never change existing event names without discussion (breaks analytics) + +### Code Quality + +- Follow DRY (Don't Repeat Yourself) principles where appropriate +- Write self-documenting code with clear variable names +- Add comments for complex logic or non-obvious decisions +- Keep functions small and focused on a single responsibility +- Handle errors appropriately with meaningful messages + +## Commit Message Guidelines + +We follow [Conventional Commits](https://www.conventionalcommits.org/) for clear, semantic commit history. + +### Format + +``` +(): + + + +