Gondulf/docs/standards/git.md

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