# Git Workflow Standard

## Overview

This project uses trunk-based development for simplicity and continuous integration.

## Branch Strategy

### Main Branch
- `main` - The primary development branch
- Always in a deployable state
- Protected branch requiring review before merge
- All commits must pass CI/CD checks

### Feature Development
- Work directly on `main` for small, low-risk changes
- Use short-lived feature branches for larger changes
- Feature branches live maximum 2 days before merging

### Branch Naming (When Used)
- `fix/brief-description` - Bug fixes
- `feature/brief-description` - New features
- `refactor/brief-description` - Code refactoring
- `docs/brief-description` - Documentation only

Examples:
- `feature/client-registration`
- `fix/token-expiration`
- `docs/api-endpoints`

## Commit Message Format

Follow Conventional Commits specification:

```
<type>(<scope>): <subject>

[optional body]

[optional footer(s)]
```

### Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only changes
- `style`: Code style changes (formatting, missing semicolons, etc)
- `refactor`: Code change that neither fixes a bug nor adds a feature
- `perf`: Performance improvements
- `test`: Adding or fixing tests
- `chore`: Changes to build process or auxiliary tools

### Scope (Optional)
Component or module affected:
- `auth`: Authorization endpoint
- `token`: Token endpoint
- `client`: Client registration
- `admin`: Administrative features
- `db`: Database changes
- `config`: Configuration changes

### Examples
```
feat(client): add self-registration endpoint

Implements dynamic client registration according to
RFC 7591 with rate limiting to prevent abuse.

Closes #12
```

```
fix(token): correct expiration time calculation
```

```
docs: update README with installation instructions
```

## Pull Request Process (When Using Branches)

1. Create branch from latest `main`
2. Make changes with clear, atomic commits
3. Ensure all tests pass locally
4. Push branch and open pull request
5. Ensure CI passes
6. Request review if required
7. Merge using "Squash and merge" for clean history

## Merge Strategy

- **Squash and merge** for feature branches (maintains clean history)
- **Fast-forward only** for direct commits to main
- Never use merge commits (no merge bubbles)

## Code Review Requirements

All code must be reviewed before merging to `main`:
- Self-review checklist:
  - Tests pass
  - Documentation updated
  - No commented-out code
  - No debug statements
  - Follows coding standards
- Peer review for significant changes

## Git Hooks (Recommended)

### Pre-commit
- Run linter (e.g., `flake8` for Python)
- Run formatter (e.g., `black` for Python)
- Check for secrets/credentials

### Pre-push
- Run test suite
- Verify no large files

## Release Process

1. Ensure all tests pass on `main`
2. Update version in appropriate files
3. Create release commit: `chore: release v{version}`
4. Tag the commit: `git tag -a v{version} -m "Release v{version}"`
5. Push tag: `git push origin v{version}`
6. Create GitHub release with release notes

## Rewriting History

- **Never** rewrite history on `main`
- Only use `git rebase` on local branches before pushing
- Use `git commit --amend` only for unpushed commits

## Large Files

- Use `.gitignore` to exclude generated files, dependencies, and build artifacts
- Never commit:
  - Binary files (unless absolutely necessary)
  - Credentials or secrets
  - Local configuration files
  - IDE-specific files
  - Log files
  - Database files

## Repository Maintenance

- Keep repository size under 100MB
- Regularly clean up merged branches
- Archive old issues and pull requests
- Maintain clear README and CONTRIBUTING files