Contributing Guide

Code of Conduct

• Be respectful and inclusive
• Focus on constructive feedback
• Help others learn and grow
• Follow project guidelines

Development Workflow

1. Issue Creation

• Check existing issues first
• Use issue templates
• Provide clear descriptions
• Add appropriate labels

2. Branch Strategy

# Feature branches
git checkout -b feature/user-authentication
git checkout -b fix/login-validation
git checkout -b docs/api-documentation

3. Commit Guidelines

# Format: type(scope): description
git commit -m "feat(auth): add JWT token validation"
git commit -m "fix(api): resolve CORS configuration"
git commit -m "docs(readme): update installation guide"

4. Pull Request Process

1. Create feature branch from develop
2. Make changes with tests
3. Update documentation
4. Submit PR with description
5. Address review feedback
6. Merge after approval

Code Standards

Python Code Style

# Use type hints
def create_user(email: str, password: str) -> User:
    """Create a new user account."""
    return User(email=email, password=hash_password(password))

# Use docstrings
class UserService:
    """Service for user management operations."""
    
    def authenticate(self, credentials: LoginCredentials) -> Optional[User]:
        """Authenticate user with provided credentials."""
        pass

TypeScript Code Style

// Use interfaces
interface UserData {
  id: string;
  email: string;
  fullName: string;
}

// Use proper error handling
const fetchUser = async (id: string): Promise<UserData> => {
  try {
    const response = await api.get(`/users/${id}`);
    return response.data;
  } catch (error) {
    throw new Error(`Failed to fetch user: ${error.message}`);
  }
};

Testing Requirements

Backend Tests

# Unit tests
def test_user_creation():
    user = create_user("test@example.com", "password123")
    assert user.email == "test@example.com"
    assert user.password != "password123"  # Should be hashed

# Integration tests
def test_login_endpoint(client):
    response = client.post("/api/v1/auth/login", json={
        "email": "test@example.com",
        "password": "password123"
    })
    assert response.status_code == 200
    assert "access_token" in response.json()

Frontend Tests

// Component tests
test('renders login form', () => {
  render(<LoginForm />);
  expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
  expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
});

// API tests
test('handles login success', async () => {
  const mockLogin = jest.fn().mockResolvedValue({ token: 'abc123' });
  const { result } = renderHook(() => useAuth());
  await act(async () => {
    await result.current.login('test@example.com', 'password');
  });
  expect(result.current.isAuthenticated).toBe(true);
});

Documentation Standards

API Documentation

• Use OpenAPI/Swagger specifications
• Include request/response examples
• Document error codes
• Provide authentication details

Code Comments

# Good: Explains why, not what
def calculate_discount(price: float, user_tier: str) -> float:
    """Calculate discount based on user tier and business rules."""
    # Premium users get 15% discount to encourage loyalty
    if user_tier == "premium":
        return price * 0.15
    return 0.0

# Bad: Explains what the code does
def calculate_discount(price: float, user_tier: str) -> float:
    # Check if user tier is premium
    if user_tier == "premium":
        # Multiply price by 0.15
        return price * 0.15
    # Return 0
    return 0.0

Review Process

Code Review Checklist

• Code follows style guidelines
• Tests are included and passing
• Documentation is updated
• No security vulnerabilities
• Performance considerations addressed
• Error handling implemented
• Logging added where appropriate

Review Guidelines

• Focus on code quality, not personal preferences
• Suggest improvements with explanations
• Approve when standards are met
• Request changes for critical issues
• Be constructive and helpful