AI-Proxy-Worker/docs/Contributing.en.md

Contributing Guide

🌍 Language / 语言

🇺🇸 English | 🇨🇳 中文

Thank you for your interest in contributing to AI Proxy Worker! This guide will help you understand how to participate in the project development.

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Git
• Cloudflare account (for testing)
• Basic knowledge of JavaScript and Cloudflare Workers

Development Setup

# Clone the repository
git clone https://github.com/qinfuyao/AI-Proxy-Worker.git
cd ai-proxy-worker

# Install dependencies
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Set up development environment
cp wrangler.toml.example wrangler.toml
# Edit wrangler.toml with your settings

🔧 Development Workflow

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/qinfuyao/AI-Proxy-Worker.git
cd ai-proxy-worker

# Add upstream remote
git remote add upstream https://github.com/original-owner/ai-proxy-worker.git

2. Create Feature Branch

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/bug-description

3. Local Development

# Start local development server
wrangler dev

# Test your changes
curl -X POST http://localhost:8787/chat \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "test"}]}'

4. Testing

# Run tests (when available)
npm test

# Manual testing checklist:
# - Basic chat functionality
# - Streaming responses
# - Error handling
# - Authentication

5. Commit and Push

# Add changes
git add .

# Commit with descriptive message
git commit -m "feat: add support for new AI model"

# Push to your fork
git push origin feature/your-feature-name

6. Create Pull Request

1. Go to your fork on GitHub
2. Click "New Pull Request"
3. Fill out the PR template
4. Wait for review

📝 Code Standards

JavaScript Style

• Use modern ES6+ features
• Follow consistent indentation (2 spaces)
• Use meaningful variable names
• Add comments for complex logic

// Good
const handleChatRequest = async (request, env) => {
  const { messages, model } = await request.json();
  
  // Validate required fields
  if (!messages || !Array.isArray(messages)) {
    throw new Error('Messages must be an array');
  }
  
  return await processChat(messages, model, env);
};

// Avoid
const h = async (r, e) => {
  const d = await r.json();
  return await p(d.m, d.mod, e);
};

Error Handling

Always provide meaningful error messages:

// Good
if (!env.DEEPSEEK_API_KEY) {
  return new Response(JSON.stringify({
    error: 'configuration_error',
    message: 'DEEPSEEK_API_KEY environment variable is required',
    timestamp: new Date().toISOString()
  }), {
    status: 500,
    headers: { 'Content-Type': 'application/json' }
  });
}

Security Best Practices

• Never log sensitive information (API keys, user data)
• Validate all input parameters
• Use proper HTTP status codes
• Implement rate limiting where appropriate

🐛 Bug Reports

Before Reporting

1. Check existing issues
2. Test with latest version
3. Reproduce the issue consistently

Bug Report Template

**Bug Description**
A clear description of what the bug is.

**Steps to Reproduce**
1. Deploy worker with configuration X
2. Send request with payload Y
3. Observe error Z

**Expected Behavior**
What should have happened.

**Environment**
- Cloudflare Workers version
- Browser/client used
- Any relevant configuration

**Additional Context**
Logs, screenshots, or other helpful information.

💡 Feature Requests

Feature Request Template

**Feature Description**
A clear description of the feature you'd like to see.

**Use Case**
Explain why this feature would be useful.

**Proposed Implementation**
If you have ideas about how to implement this.

**Alternatives Considered**
Other solutions you've considered.

📖 Documentation

Writing Guidelines

• Use clear, concise language
• Provide practical examples
• Include both English and Chinese versions
• Test all code examples

Documentation Structure

docs/
├── Installation.md/en.md     # Setup guides
├── Configuration.md/en.md    # Configuration options
├── API-Reference.md/en.md    # API documentation
├── Examples.md/en.md         # Usage examples
├── Troubleshooting.md/en.md  # Common issues
└── Contributing.md/en.md     # This file

🔄 Release Process

Version Numbering

We follow Semantic Versioning:

• MAJOR.MINOR.PATCH
• Major: Breaking changes
• Minor: New features, backward compatible
• Patch: Bug fixes

Release Checklist

• Update version in wrangler.toml
• Update CHANGELOG.md
• Test all functionality
• Update documentation
• Create release notes
• Tag release

🏆 Recognition

Contributors

All contributors will be recognized in:

• README.md contributors section
• Release notes
• GitHub contributors page

Types of Contributions

• 🐛 Bug fixes
• ✨ New features
• 📝 Documentation
• 🎨 UI/UX improvements
• 🔧 Infrastructure
• 🌍 Translations

❓ Getting Help

Community Support

• 💡 Discussions - General questions
• 📋 Issues - Bug reports and feature requests
• [Discord/Slack] - Real-time chat (if available)

Code Review Process

1. All PRs require at least one review
2. Maintainers will review within 48 hours
3. Address feedback promptly
4. Squash commits before merging

📋 Contribution Checklist

Before submitting a PR, ensure:

• Code follows project style guidelines
• All tests pass
• Documentation updated if needed
• Commit messages are descriptive
• PR description explains the changes
• No sensitive information in code
• Feature works in production environment

---

Thank you for contributing to AI Proxy Worker! 🎉

Your contributions make this project better for everyone.