headquarter/docs/development/contributing.md

Contributing Guide

Welcome

Thank you for your interest in contributing to Headquarter! This document provides guidelines and workflows for contributing.

Getting Started

1. Fork the repository
2. Clone your fork: git clone https://github.com/your-username/headquarter.git
3. Set up development environment (see Setup Guide)
4. Create a branch: git checkout -b feature/your-feature

Development Workflow

1. Find or Create an Issue

• Check existing issues for something to work on
• Create an issue to discuss new features before implementing
• Comment on issues to claim them

2. Create a Branch

# Feature branch
git checkout -b feature/description

# Bug fix branch
git checkout -b fix/description

# Documentation branch
git checkout -b docs/description

3. Make Changes

• Write clear, concise code
• Follow existing patterns and conventions
• Add tests for new functionality
• Update documentation as needed

4. Run Quality Gates

# Backend
cd apps/api
ruff check src/ tests/
mypy src/
pytest

# Frontend
cd apps/web
npm run lint
npm run typecheck
npm run test
npm run build

5. Commit Changes

We use conventional commits:

# Format: type(scope): description

# Examples:
git commit -m "feat(auth): add OAuth2 login"
git commit -m "fix(api): handle missing user gracefully"
git commit -m "docs(readme): update installation instructions"
git commit -m "test(git): add URL parsing tests"
git commit -m "refactor(models): extract base repository"

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• style: Formatting (no code change)
• refactor: Code restructuring
• test: Adding tests
• chore: Maintenance tasks

6. Push and Create Pull Request

git push origin feature/description

PR Description should include:

• What changed and why
• How to test
• Screenshots (for UI changes)
• Link to related issue

Code Standards

Python (Backend)

Style: Follow PEP 8 and project conventions

# Function naming: snake_case
def get_user_by_id(user_id: str) -> User | None:
    pass

# Class naming: PascalCase
class GitRepositoryService:
    pass

# Constants: UPPER_SNAKE_CASE
MAX_FILE_SIZE = 1024 * 1024  # 1MB

# Type hints required
def process_data(data: dict[str, Any]) -> ProcessedResult:
    pass

Docstrings: Google style

def extract_base_repo_url(url: str) -> str | None:
    """Extract base repository URL from a browser URL.
    
    Args:
        url: The URL to parse, may be a browser URL or git URL.
        
    Returns:
        The base repository URL with .git suffix, or None if parsing fails.
        
    Examples:
        >>> extract_base_repo_url("https://github.com/user/repo/tree/main")
        'https://github.com/user/repo.git'
        
        >>> extract_base_repo_url("https://github.com/user/repo.git")
        'https://github.com/user/repo.git'
    """
    pass

TypeScript (Frontend)

Style: Follow existing patterns

// Interface naming: PascalCase
interface User {
  id: string;
  email: string;
  name: string;
}

// Function naming: camelCase
function getUserById(userId: string): Promise<User> {
  return api.get(`/users/${userId}`);
}

// Component naming: PascalCase
const UserProfile: React.FC<UserProfileProps> = ({ user }) => {
  return <div>{user.name}</div>;
};

Testing Requirements

New Features

• Unit tests for business logic
• Integration tests for API endpoints
• Component tests for UI components

Bug Fixes

• Regression test that would catch the bug
• Verify fix with the test

Example

# Backend test
def test_extract_github_browser_url():
    url = "https://github.com/user/repo/tree/main"
    result = extract_base_repo_url(url)
    assert result == "https://github.com/user/repo.git"

# Frontend test
test('shows file tree', () => {
  render(<FileTree files={mockFiles} onFileClick={() => {}} />);
  expect(screen.getByText('src')).toBeInTheDocument();
});

Documentation

Update documentation when:

• Adding new features
• Changing API endpoints
• Modifying configuration
• Adding environment variables

Documentation locations:

• README.md - Project overview
• docs/features/ - Feature documentation
• docs/api/ - API documentation
• docs/deployment/ - Deployment guides

Review Process

1. Automated checks must pass (CI/CD)
2. Code review by at least one maintainer
3. Approval required before merge
4. Squash merge to keep history clean

Review Checklist

For Authors:

• Tests pass locally
• Quality gates pass
• Documentation updated
• PR description is clear

For Reviewers:

• Code makes sense
• Tests cover changes
• No security issues
• Follows conventions

Release Process

1. Update version in pyproject.toml and package.json
2. Update CHANGELOG.md
3. Create git tag: git tag v1.2.3
4. Push tag: git push origin v1.2.3
5. Create GitHub release with notes

Community

Communication Channels

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions and ideas
• Pull Requests: Code contributions

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers
• Focus on constructive feedback
• Respect different viewpoints

Questions?

• Check existing documentation
• Search closed issues
• Ask in GitHub Discussions
• Join community chat (if available)

Resources

• Development Setup
• Testing Guide
• Quality Gates
• Project README