docs: comprehensive documentation overhaul
Add complete documentation structure: - Frontend architecture documentation - Database schema documentation - Deployment guides (Docker, Traefik, Authentik, Environment) - Development guides (Setup, Testing, Contributing, Quality Gates) - Deployment architecture documentation - Updated docs README with complete navigation All new features and APIs are now documented. Quality gates: docs only, no code changes
This commit is contained in:
Fusion
@@ -0,0 +1,261 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user