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](./setup.md))
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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
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

```python
# 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
```python
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

```typescript
// 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

```python
# 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](./setup.md)
- [Testing Guide](./testing.md)
- [Quality Gates](./quality-gates.md)
- [Project README](../../README.md)