OGT Docs - Rules Git

Complete guide for creating and managing Git workflow rules.

Overview

Git rules establish consistent version control practices. They cover commit messages, branch naming, pull request requirements, and code review standards.

mermaid

flowchart TB
    subgraph git ["docs/rules/git/"]
        C["commits/"]
        B["branches/"]
        P["pull_requests/"]
        R["reviews/"]
        M["merging/"]
        T["tags/"]
    end

    C --> |format| CM["Conventional Commits"]
    B --> |naming| BN["Branch Patterns"]
    P --> |requirements| PR["PR Templates"]
    R --> |standards| RS["Review Checklists"]

When to Use

Establishing commit message conventions
Defining branch naming patterns
Setting PR requirements and templates
Creating code review standards
Defining merge strategies
Setting up release tagging

Folder Structure

docs/rules/git/
├── commits/                        # Commit message rules
│   ├── rule.md
│   ├── examples.md
│   ├── .version
│   └── .enforced_by
│
├── branches/                       # Branch naming rules
│   ├── rule.md
│   ├── examples.md
│   └── .enforced_by
│
├── pull_requests/                  # PR requirements
│   ├── rule.md
│   ├── template.md                 # PR template
│   ├── examples.md
│   └── .enforced_by
│
├── reviews/                        # Code review standards
│   ├── rule.md
│   ├── checklist.md               # Review checklist
│   └── examples.md
│
├── merging/                        # Merge strategy rules
│   ├── rule.md
│   └── examples.md
│
└── tags/                           # Release tagging rules
    ├── rule.md
    └── examples.md

Example: docs/rules/git/commits/

Commit message format rules.

Folder Structure

docs/rules/git/commits/
├── rule.md
├── examples.md
├── .version
└── .enforced_by

rule.md

markdown

# Rule: Commit Message Format

## Summary

All commit messages MUST follow Conventional Commits format.

## Rationale

Consistent commit messages enable:

- Automated changelog generation
- Semantic versioning automation
- Easy history navigation
- Clear communication of changes

## The Rule

### Format

[optional body]

[optional footer(s)]


### Types

| Type | Use When |
|------|----------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting, no code change |
| `refactor` | Neither fixes nor adds feature |
| `perf` | Performance improvement |
| `test` | Adding/updating tests |
| `chore` | Maintenance tasks |
| `ci` | CI/CD changes |
| `build` | Build system changes |

### Requirements

1. **MUST** use lowercase type
2. **MUST** use imperative mood ("add" not "added")
3. **MUST** limit first line to 72 characters
4. **SHOULD** include scope for clarity
5. **MUST** reference issue number for bug fixes
6. **MUST** mark breaking changes with `!` or footer

### Breaking Changes

Two ways to indicate breaking changes:

feat(api)!: change auth header format

Or:

feat(api): change auth header format

BREAKING CHANGE: Authorization header now requires "Bearer " prefix


## Examples

### Correct

feat(auth): add Steam OAuth provider

Implement Steam OpenID authentication flow. Follows existing Google/Discord pattern.

Closes #456

undefined

fix(api): handle null response from legacy endpoint

The /v0/users endpoint can return null for deleted users. Add null check and return 404 instead of 500.

Fixes #789

undefined

refactor(components): extract CardBase from entity cards

DRY refactor - all entity cards now extend CardBase. No functional changes.


### Incorrect

Fixed bug # No type, vague FEAT: Add feature # Wrong case feat(auth): Added Steam OAuth # Past tense feat: implement the new system... # Too long (>72 chars)


## Exceptions

- Merge commits may use default message
- Revert commits may use git's default format

## Enforcement

- commitlint in pre-commit hook
- CI check on PRs
- PR review

## References

- [Conventional Commits](https://www.conventionalcommits.org/)

examples.md

markdown

# Commit Message Examples

## Feature Commits

feat(creatures): add CR filtering to creature list

Allow filtering creatures by Challenge Rating range. Uses dual-handle slider component.

Related: #234

undefined

feat(search): implement fuzzy search with MiniSearch

Replace substring matching with indexed fuzzy search. Results ranked by relevance score.

Performance: <16ms for 10k entries

Closes #567


## Bug Fix Commits

fix(cards): prevent image flash on card hover

Card images were reloading on every hover due to missing key prop in map. Add stable key based on entity slug.

Fixes #890

undefined

fix(auth): handle expired refresh tokens gracefully

When refresh token expires, redirect to login instead of showing error page. Clear local storage on redirect.

Fixes #891 Fixes #892


## Refactor Commits

refactor(services): extract API client from services

Move HTTP logic to dedicated ApiClient class. Services now use dependency injection.

No functional changes. Improves testability.


## Documentation Commits

docs(readme): add Docker setup instructions

Document docker-compose workflow for new developers. Include troubleshooting section for common issues.


## Breaking Change Commits

feat(api)!: rename /monsters to /creatures

BREAKING CHANGE: All /api/monsters/_ endpoints now at /api/creatures/_

Migration:

Update all fetch calls
/monsters/:slug -> /creatures/:slug

Deprecation notice sent 2026-01-01. Old endpoints removed 2026-02-01.


## Chore Commits

chore(deps): update dependencies

react 18.2 -> 19.0
vite 5.0 -> 7.3
typescript 5.3 -> 5.8

No breaking changes.


## CI Commits

ci(github): add automated release workflow

Trigger on version tags, build and publish to npm. Uses semantic-release for changelog generation.

undefined

.enforced_by

commitlint
husky pre-commit hook
GitHub Actions CI
PR review checklist

Example: docs/rules/git/branches/

Branch naming conventions.

rule.md

markdown

# Rule: Branch Naming Conventions

## Summary

All branches MUST follow the pattern `{type}/{ticket}-{description}`.

## Rationale

Consistent branch naming:

- Links work to tickets/issues
- Indicates purpose at a glance
- Enables automation (CI triggers, auto-linking)
- Simplifies cleanup

## The Rule

### Format

{type}/{ticket}-{short-description}


### Types

| Type | Use For |
|------|---------|
| `feature` | New features |
| `fix` | Bug fixes |
| `hotfix` | Urgent production fixes |
| `refactor` | Code refactoring |
| `docs` | Documentation |
| `test` | Test additions |
| `chore` | Maintenance |
| `release` | Release preparation |

### Requirements

1. **MUST** use lowercase
2. **MUST** include ticket number (or `no-ticket` if none)
3. **MUST** use hyphens for word separation
4. **SHOULD** keep description under 30 characters
5. **MUST NOT** include special characters except hyphen

### Protected Branches

- `main` - Production code
- `develop` - Integration branch (if used)

**MUST NOT** push directly to protected branches.

## Examples

### Correct

feature/ORC-123-steam-oauth fix/ORC-456-null-response-crash hotfix/ORC-789-login-broken refactor/ORC-101-extract-card-base docs/no-ticket-api-readme chore/ORC-202-update-deps release/v1.2.0


### Incorrect

steam-oauth # No type, no ticket feature/steam_oauth # Underscores Feature/ORC-123-Steam-OAuth # Uppercase feature/ORC-123-implement-the-new-steam-oauth-provider # Too long feature/steam oauth # Spaces


## Exceptions

- `main`, `develop` are allowed as-is
- Dependabot branches follow their own format

## Enforcement

- Branch protection rules
- CI validation
- PR checks

Example: docs/rules/git/pull_requests/

PR requirements and templates.

rule.md

markdown

# Rule: Pull Request Requirements

## Summary

All PRs MUST include a description, link to ticket, and pass CI checks.

## Rationale

Well-documented PRs:

- Enable effective code review
- Provide context for future readers
- Link work to requirements
- Ensure quality before merge

## The Rules

### Required Elements

1. **MUST** have descriptive title (not branch name)
2. **MUST** include summary of changes
3. **MUST** link to ticket/issue
4. **MUST** pass all CI checks
5. **MUST** have at least one approval (for non-trivial changes)
6. **SHOULD** include testing notes
7. **SHOULD** include screenshots for UI changes

### Title Format

[TYPE] Brief description (#ticket)


Examples:
- `[Feature] Add Steam OAuth (#ORC-123)`
- `[Fix] Handle null API response (#ORC-456)`
- `[Refactor] Extract CardBase component (#ORC-101)`

### Size Guidelines

- **SHOULD** be under 400 lines changed
- Large PRs **SHOULD** be split into smaller PRs
- If >400 lines, add explanation of why

### Review Requirements

| Change Type | Required Approvals |
|-------------|-------------------|
| Documentation only | 0 (self-merge OK) |
| Small fix (<50 lines) | 1 |
| Feature/Refactor | 1 |
| Breaking change | 2 |
| Security-related | 2 |

## Exceptions

- Automated dependency updates may auto-merge if CI passes
- Documentation-only changes may self-merge

## Enforcement

- GitHub branch protection rules
- Required status checks
- PR template

template.md

markdown

## Summary

Brief description of what this PR does.

## Related Issue

Fixes #(issue number)

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)
- [ ] Chore (dependencies, build, CI)

## Changes Made

- Change 1
- Change 2
- Change 3

## Testing

Describe how you tested these changes:

- [ ] Unit tests added/updated
- [ ] Manual testing performed
- [ ] E2E tests added/updated

## Screenshots (if applicable)

| Before | After |
| ------ | ----- |
| img    | img   |

## Checklist

- [ ] My code follows the project's coding standards
- [ ] I have performed a self-review of my code
- [ ] I have commented my code where needed
- [ ] I have updated the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix/feature works
- [ ] New and existing tests pass locally
- [ ] Any dependent changes have been merged

Example: docs/rules/git/reviews/

Code review standards.

rule.md

markdown

# Rule: Code Review Standards

## Summary

All code reviews MUST be constructive, timely, and thorough.

## Rationale

Effective code review:

- Catches bugs before production
- Shares knowledge across team
- Maintains code quality
- Improves developer skills

## The Rules

### Reviewer Responsibilities

1. **MUST** respond within 24 hours (business days)
2. **MUST** provide actionable feedback
3. **MUST** approve or request changes (no silent stalls)
4. **SHOULD** suggest alternatives when blocking
5. **MUST** distinguish blocking vs. non-blocking comments

### Comment Conventions

Use prefixes to clarify intent:

| Prefix        | Meaning                   | Blocking? |
| ------------- | ------------------------- | --------- |
| `blocker:`    | Must fix before merge     | Yes       |
| `question:`   | Need clarification        | Maybe     |
| `suggestion:` | Consider this alternative | No        |
| `nit:`        | Minor style preference    | No        |
| `praise:`     | Positive feedback         | No        |

### What to Review

1. **Correctness**: Does it do what it claims?
2. **Design**: Is the approach appropriate?
3. **Readability**: Is it understandable?
4. **Tests**: Are changes tested?
5. **Documentation**: Are comments/docs updated?
6. **Security**: Any security concerns?
7. **Performance**: Any performance issues?

### Author Responsibilities

1. **MUST** respond to all comments
2. **MUST** resolve or discuss blockers
3. **SHOULD** implement non-blocking suggestions or explain why not
4. **MUST NOT** merge with unresolved blockers

## Examples

### Good Review Comments

blocker: This query is vulnerable to SQL injection. Use parameterized queries instead:

db.query('SELECT * FROM users WHERE id = ?', [userId])

question: Why is this timeout set to 30 seconds? Seems long for a user-facing request.

suggestion: Consider extracting this into a helper function. It's used in three places.

nit: Prefer

const

over

let

here since it's never reassigned.

praise: Nice use of discriminated unions here! Makes the error handling very clean.


### Poor Review Comments

This is wrong. # No explanation I wouldn't do it this way. # No alternative ??? # Meaningless LGTM # (for complex PR without real review)


## Enforcement

- Review time tracked in GitHub insights
- Stale PR alerts
- Review checklist in PR template

checklist.md

markdown

# Code Review Checklist

Use this checklist when reviewing PRs:

## Basics

- [ ] PR description explains the changes
- [ ] Related issue is linked
- [ ] CI checks pass

## Code Quality

- [ ] Code follows project coding standards
- [ ] No unnecessary complexity
- [ ] No code duplication
- [ ] Functions/methods have single responsibility
- [ ] Names are clear and descriptive

## Correctness

- [ ] Logic is correct
- [ ] Edge cases are handled
- [ ] Error handling is appropriate
- [ ] No obvious bugs

## Testing

- [ ] New code has tests
- [ ] Tests cover edge cases
- [ ] Existing tests still pass
- [ ] Test names describe what they test

## Security

- [ ] No secrets in code
- [ ] Input is validated
- [ ] No SQL injection risks
- [ ] No XSS vulnerabilities
- [ ] Auth/authz is correct

## Performance

- [ ] No N+1 queries
- [ ] No unnecessary re-renders
- [ ] Large data sets paginated
- [ ] Expensive operations optimized or async

## Documentation

- [ ] Code comments where needed
- [ ] API docs updated
- [ ] README updated if needed

## Final

- [ ] I would be comfortable maintaining this code
- [ ] Changes match what the PR description claims

Example: docs/rules/git/merging/

Merge strategy rules.

rule.md

markdown

# Rule: Merge Strategy

## Summary

All merges to main MUST use squash merge with a descriptive commit message.

## Rationale

Squash merging:

- Keeps main history clean
- Each commit represents one complete feature/fix
- Simplifies git bisect
- Enables clean reverts

## The Rules

### Default: Squash Merge

1. **MUST** use squash merge for feature branches
2. **MUST** write descriptive squash commit message
3. **SHOULD** include PR number in commit message
4. **MUST** delete branch after merge

### Exceptions: Regular Merge

Use regular merge only for:

- Release branches to main (preserve history)
- Long-running branches with meaningful commits

### Commit Message for Squash

Follow same format as regular commits:

feat(auth): add Steam OAuth provider (#123)

Implement Steam OpenID authentication flow including:

Steam provider configuration
Callback handler
Session management

Closes #456


### Branch Cleanup

**MUST** delete merged branches:
- GitHub: Enable "Automatically delete head branches"
- Local: `git fetch --prune` regularly

## Enforcement

- GitHub branch protection: Require squash merge
- Automatic branch deletion enabled
- CI reminder for stale branches

Example: docs/rules/git/tags/

Release tagging rules.

rule.md

markdown

# Rule: Release Tags

## Summary

All releases MUST be tagged with semantic version following `v{major}.{minor}.{patch}`.

## Rationale

Semantic versioning:

- Communicates impact of changes
- Enables automated releases
- Provides clear upgrade path
- Links releases to code state

## The Rules

### Version Format

v{MAJOR}.{MINOR}.{PATCH}


- **MAJOR**: Breaking changes
- **MINOR**: New features, backward compatible
- **PATCH**: Bug fixes, backward compatible

### Pre-release Tags

v1.2.0-alpha.1 v1.2.0-beta.1 v1.2.0-rc.1


### Tagging Process

1. **MUST** tag from main branch
2. **MUST** update version in package.json first
3. **MUST** use annotated tags (not lightweight)
4. **MUST** include release notes in tag message

```bash
# Correct
git tag -a v1.2.0 -m "Release v1.2.0: Feature X, Fix Y"

# Incorrect
git tag v1.2.0  # Lightweight tag, no message

Release Notes

MUST include:

Summary of changes
Breaking changes (if any)
Migration notes (if needed)
Contributors

Examples

Correct Tags

v1.0.0          # First stable release
v1.1.0          # New feature
v1.1.1          # Bug fix
v2.0.0          # Breaking change
v2.0.0-beta.1   # Pre-release

Incorrect Tags

1.0.0           # Missing 'v' prefix
v1.0            # Missing patch version
release-1.0.0   # Wrong format
v1.0.0.0        # Too many parts

Enforcement

CI validates tag format
Release workflow triggered by tags
Changelog generated from commits


---

## Creating New Git Rules

```mermaid
flowchart TD
    A[Identify Need] --> B{Category}

    B -->|Commit| C[commits/]
    B -->|Branch| D[branches/]
    B -->|PR| E[pull_requests/]
    B -->|Review| F[reviews/]
    B -->|Merge| G[merging/]
    B -->|Release| H[tags/]

    C --> I[Create Folder]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I

    I --> J[Write rule.md]
    J --> K[Add examples.md]
    K --> L{Has Template?}

    L -->|Yes| M[Add template.md]
    L -->|No| N[Configure Enforcement]
    M --> N

    N --> O{Enforcement Type}
    O -->|Hook| P[Add to husky]
    O -->|CI| Q[Add GH Action]
    O -->|GitHub| R[Configure Settings]

    P --> S[Document in .enforced_by]
    Q --> S
    R --> S

    S --> T[Announce to Team]

Signal Files Reference

Signal	Type	Content	Purpose
`.version`	Content	JSON schema version	Track rule version
`.enforced_by`	Content	List of tools	Document enforcement
`.deprecated`	Empty	-	Mark as deprecated
`.template`	Content	Template file path	Link to templates

Rule Quality Checklist

Before finalizing a git rule:

Rule is clear and unambiguous
Format patterns are documented
At least 3 correct examples
At least 3 incorrect examples
Exceptions are documented
Enforcement mechanism configured
GitHub settings updated if needed
Pre-commit hooks updated if needed
CI workflow added if needed
Team notified of new rule

ogt-docs-rules-git

NPX Install

Tags

SKILL.md Content

OGT Docs - Rules Git

Overview

When to Use

Folder Structure

Example: docs/rules/git/commits/

Folder Structure

rule.md

examples.md

.enforced_by

Example: docs/rules/git/branches/

rule.md

Example: docs/rules/git/pull_requests/

rule.md

template.md

Example: docs/rules/git/reviews/

rule.md

checklist.md

Example: docs/rules/git/merging/

rule.md

Example: docs/rules/git/tags/

rule.md

Release Notes

Examples

Correct Tags

Incorrect Tags

Enforcement

Signal Files Reference

Rule Quality Checklist