frontend-svelte/docs/GIT_WORKFLOW.md

# Git Workflow and Branching Strategy

This document outlines the git workflow, branching strategy, commit conventions, and code review guidelines for the glyphdiff.com project.

## Table of Contents

1. [Branching Strategy](#branching-strategy)
2. [Branch Naming Conventions](#branch-naming-conventions)
3. [Commit Message Conventions](#commit-message-conventions)
4. [Code Splitting and Merge Request Guidelines](#code-splitting-and-merge-request-guidelines)
5. [Branch Protection Rules](#branch-protection-rules)
6. [Git Hooks Configuration](#git-hooks-configuration)

---

## Branching Strategy

We use a Gitflow-inspired branching strategy adapted for our development workflow. This strategy provides a clear structure for feature development, bug fixes, and releases.

### Branch Types

#### 1. `main` Branch
- **Purpose**: Production-ready code only
- **Protection**: Highest level of protection
- **Rules**:
  - Only merge `release/*` or `hotfix/*` branches into `main`
  - No direct commits allowed
  - Must pass all tests and code reviews
  - Tags are created from this branch for releases (e.g., `v1.0.0`)

#### 2. `develop` Branch
- **Purpose**: Integration branch for features
- **Protection**: High level of protection
- **Rules**:
  - Merge `feature/*` and `fix/*` branches into `develop`
  - No direct commits allowed
  - Must pass all tests before merging
  - Serves as the base for `release/*` branches

#### 3. `feature/*` Branches
- **Purpose**: Develop new features
- **Naming**: `feature/feature-name` (e.g., `feature/font-catalog`, `feature/comparison-grid`)
- **Base**: Always branch from `develop`
- **Merge**: Merge back into `develop` via Merge Request (MR)
- **Rules**:
  - One feature per branch
  - Keep branches focused and small
  - Delete after merging

#### 4. `fix/*` Branches
- **Purpose**: Fix bugs discovered during development
- **Naming**: `fix/issue-description` (e.g., `fix/font-loading-error`, `fix/responsive-layout`)
- **Base**: Branch from `develop`
- **Merge**: Merge back into `develop` via MR
- **Rules**:
  - One fix per branch
  - Include tests that verify the fix
  - Delete after merging

#### 5. `hotfix/*` Branches
- **Purpose**: Critical fixes for production issues
- **Naming**: `hotfix/critical-fix` (e.g., `hotfix/security-patch`, `hotfix-production-crash`)
- **Base**: Branch from `main`
- **Merge**: Merge into both `main` and `develop`
- **Rules**:
  - Use only for production emergencies
  - Must be thoroughly tested
  - Create a release tag after merging to `main`

#### 6. `release/*` Branches
- **Purpose**: Prepare for a new release
- **Naming**: `release/vX.Y.Z` (e.g., `release/v1.0.0`, `release/v1.1.0`)
- **Base**: Branch from `develop`
- **Merge**: Merge into both `main` and `develop`
- **Rules**:
  - Finalize release notes
  - Update version numbers
  - Perform final testing
  - Create release tag after merging to `main`

### Branch Workflow Diagram

```
main (production)
  ↑
  │ hotfix/*, release/*
  │
develop (integration)
  ↑
  │ feature/*, fix/*
  │
feature branches
```

---

## Branch Naming Conventions

### Feature Branches
- Format: `feature/feature-name`
- Examples:
  - `feature/font-catalog`
  - `feature/comparison-grid`
  - `feature/dark-mode`
  - `feature/google-fonts-integration`

### Fix Branches
- Format: `fix/issue-description`
- Examples:
  - `fix/font-loading-error`
  - `fix/responsive-layout`
  - `fix/state-persistence`
  - `fix-accessibility-contrast`

### Hotfix Branches
- Format: `hotfix/critical-fix`
- Examples:
  - `hotfix/security-patch`
  - `hotfix-production-crash`
  - `hotfix-api-rate-limit`

### Release Branches
- Format: `release/vX.Y.Z`
- Examples:
  - `release/v1.0.0`
  - `release/v1.1.0`
  - `release/v2.0.0`

### Naming Guidelines
- Use lowercase letters
- Use hyphens to separate words
- Be descriptive but concise
- Avoid special characters (except hyphens)
- Keep names under 50 characters

---

## Commit Message Conventions

We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This format enables automated changelog generation and better commit history readability.

### Format

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

<body>

<footer>
```

### Commit Types

| Type | Description | Examples |
|------|-------------|----------|
| `feat` | New feature | `feat(fonts): add Google Fonts integration` |
| `fix` | Bug fix | `fix(comparison): resolve font loading race condition` |
| `docs` | Documentation changes | `docs(readme): update installation instructions` |
| `style` | Code style changes (formatting, etc.) | `style(components): format with Prettier` |
| `refactor` | Code refactoring | `refactor(stores): simplify state management` |
| `test` | Adding or updating tests | `test(fonts): add unit tests for font mapper` |
| `chore` | Maintenance tasks | `chore(deps): update Tailwind CSS to v4.0` |
| `perf` | Performance improvements | `perf(catalog): implement lazy loading for fonts` |

### Scope

The scope provides context about which part of the codebase is affected. Common scopes for this project:

- `fonts` - Font-related functionality
- `comparison` - Font comparison features
- `catalog` - Font catalog pages
- `stores` - State management stores
- `components` - UI components
- `routes` - SvelteKit routes
- `services` - External API services
- `utils` - Utility functions
- `types` - TypeScript type definitions
- `ui` - UI-related changes (theme, layout, etc.)
- `config` - Configuration files

### Subject

- Use imperative mood ("add" not "added", "fix" not "fixed")
- Keep it short (50 characters or less)
- Don't end with a period
- Be specific and descriptive

### Body

- Use imperative mood
- Explain **what** and **why**, not **how**
- Wrap at 72 characters
- Include references to issues (e.g., `Closes #123`)

### Footer

- Reference breaking changes with `BREAKING CHANGE:`
- Reference issues with `Closes #123` or `Fixes #456`
- Include co-authors if needed

### Examples

#### Feature Commit
```
feat(fonts): add Google Fonts API integration

Implement Google Fonts API service to fetch and display available fonts.
This includes the fetchGoogleFonts function and font mapper utilities.

Closes #12
```

#### Bug Fix Commit
```
fix(comparison): resolve font loading race condition

The comparison grid was attempting to render fonts before they were fully
loaded. Added loading state checks to prevent this issue.

Fixes #45
```

#### Refactor Commit
```
refactor(stores): simplify state management with Svelte 5 runes

Migrated from Svelte stores to Svelte 5's $state runes for better
performance and simpler code. This change affects all stores in the
project.

BREAKING CHANGE: Store API has changed from subscribe() to direct
property access. Update all store consumers accordingly.
```

#### Documentation Commit
```
docs(git-workflow): add commit message conventions

Document the conventional commits format with examples and guidelines
for the team.
```

#### Chore Commit
```
chore(deps): update Tailwind CSS to v4.0.0

Update Tailwind CSS to the latest version and adjust configuration
files accordingly.
```

---

## Code Splitting and Merge Request Guidelines

### Merge Request Size Guidelines

- **Maximum MR size**: < 500 lines changed (additions + deletions)
- **Ideal MR size**: 100-300 lines changed
- **Files per MR**: < 10 files

### When to Split a Feature into Multiple MRs

Split a feature into multiple MRs when:

1. **The feature is large** (> 500 lines or > 10 files)
2. **Multiple concerns are involved** (e.g., UI + API + state management)
3. **Independent parts can be tested separately**
4. **The feature has logical phases** (e.g., setup → implementation → polish)

### Example: Splitting a Feature

**Feature**: Font Catalog with Filtering

**MR 1**: `feature/font-catalog-setup`
- Create basic catalog page structure
- Set up routing
- Add placeholder components
- ~150 lines

**MR 2**: `feature/font-catalog-data`
- Implement Google Fonts API integration
- Create font data fetching logic
- Add font mapper utilities
- ~200 lines

**MR 3**: `feature/font-catalog-ui`
- Build FontCard component
- Implement grid layout
- Add loading states
- ~250 lines

**MR 4**: `feature/font-catalog-filtering`
- Implement filter store
- Build FilterBar component
- Connect filters to catalog
- ~180 lines

### Merge Request Description Template

Every MR must include a comprehensive description:

```markdown
## Description
Brief description of what this MR changes and why.

## Changes Made
- [ ] Change 1
- [ ] Change 2
- [ ] Change 3

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Refactoring
- [ ] Performance improvement

## Testing
- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] Tested on Chrome
- [ ] Tested on Firefox
- [ ] Tested on Safari
- [ ] Tested on mobile (responsive)

## Screenshots (if applicable)
Add screenshots or GIFs showing the changes.

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added/updated
- [ ] All tests passing

## Related Issues
Closes #123
Related to #456
```

### Code Review Checklist

Reviewers should check:

#### Functionality
- [ ] Does the code work as intended?
- [ ] Are edge cases handled?
- [ ] Is error handling appropriate?

#### Code Quality
- [ ] Is the code readable and maintainable?
- [ ] Are variable/function names descriptive?
- [ ] Is there unnecessary complexity?
- [ ] Are there code duplications?

#### Best Practices
- [ ] Does it follow project conventions?
- [ ] Are TypeScript types properly defined?
- [ ] Are Svelte best practices followed?
- [ ] Is Tailwind CSS used appropriately?

#### Testing
- [ ] Are tests included?
- [ ] Do tests cover edge cases?
- [ ] Are tests meaningful and not redundant?

#### Documentation
- [ ] Is the code self-documenting?
- [ ] Are complex functions commented?
- [ ] Is the MR description clear?

#### Performance
- [ ] Are there performance concerns?
- [ ] Is lazy loading used where appropriate?
- [ ] Are unnecessary re-renders avoided?

### Merge Request Approval Process

1. **Author**: Creates MR with complete description
2. **Reviewer**: Reviews code using the checklist above
3. **Discussion**: Address any concerns or suggestions
4. **Approval**: At least one approval required
4. **Merge**: Squash and merge into target branch
5. **Cleanup**: Delete source branch after merge

---

## Branch Protection Rules

### `main` Branch Protection

- **Require pull request reviews**: Yes
  - Required approvers: 1
  - Dismiss stale reviews: Yes
- **Require status checks**: Yes
  - Required checks: All tests, linting
  - Require branches to be up to date: Yes
- **Restrict who can push**: Only maintainers
- **Require linear history**: Yes (squash and merge)
- **Block force pushes**: Yes

### `develop` Branch Protection

- **Require pull request reviews**: Yes
  - Required approvers: 1
  - Dismiss stale reviews: Yes
- **Require status checks**: Yes
  - Required checks: All tests, linting
  - Require branches to be up to date: Yes
- **Restrict who can push**: Only developers and maintainers
- **Require linear history**: Yes (squash and merge)
- **Block force pushes**: Yes

### Implementation Notes

These rules should be configured in your Git hosting platform (GitHub, GitLab, or Bitbucket). The exact configuration steps vary by platform:

- **GitHub**: Settings → Branches → Add rule
- **GitLab**: Settings → Repository → Protected branches
- **Bitbucket**: Repository settings → Branch restrictions

---

## Git Hooks Configuration

Git hooks are automated scripts that run at specific points in the git workflow. They help maintain code quality and consistency.

### Recommended Hooks

#### 1. Pre-commit Hook
**Purpose**: Run linter and formatter before committing

**Tools**: ESLint, Prettier

**Implementation**:
```bash
#!/bin/sh
# .git/hooks/pre-commit

# Run Prettier
npm run format:check

# Run ESLint
npm run lint

# Exit with error if any check fails
if [ $? -ne 0 ]; then
  echo "❌ Pre-commit checks failed. Please fix the issues before committing."
  exit 1
fi

echo "✅ Pre-commit checks passed."
```

**Setup**:
```bash
# Install husky (recommended)
npm install --save-dev husky

# Initialize husky
npx husky install

# Add pre-commit hook
npx husky add .husky/pre-commit "npm run lint && npm run format:check"
```

#### 2. Commit-msg Hook
**Purpose**: Validate commit message format

**Tools**: commitlint

**Implementation**:
```bash
#!/bin/sh
# .git/hooks/commit-msg

# Validate commit message with commitlint
npx --no -- commitlint --edit $1
```

**Setup**:
```bash
# Install commitlint
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# Create commitlint config
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

# Add commit-msg hook
npx husky add .husky/commit-msg "npx --no -- commitlint --edit \$1"
```

#### 3. Pre-push Hook
**Purpose**: Run tests before pushing

**Tools**: Vitest, SvelteKit test runner

**Implementation**:
```bash
#!/bin/sh
# .git/hooks/pre-push

# Run tests
npm run test

# Exit with error if tests fail
if [ $? -ne 0 ]; then
  echo "❌ Tests failed. Please fix the failing tests before pushing."
  exit 1
fi

echo "✅ All tests passed."
```

**Setup**:
```bash
# Add pre-push hook
npx husky add .husky/pre-push "npm run test"
```

### Alternative: Using Husky

[Husky](https://typicode.github.io/husky/) is a popular tool for managing git hooks. It's easier to maintain and works across different operating systems.

**Installation**:
```bash
npm install --save-dev husky
npx husky install
npm pkg set scripts.prepare="husky install"
```

**Adding hooks**:
```bash
# Pre-commit hook
npx husky add .husky/pre-commit "npm run lint && npm run format:check"

# Commit-msg hook
npx husky add .husky/commit-msg "npx --no -- commitlint --edit \$1"

# Pre-push hook
npx husky add .husky/pre-push "npm run test"
```

### Hook Scripts for This Project

Once the project is set up with SvelteKit, add these scripts to `package.json`:

```json
{
  "scripts": {
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "test": "vitest run",
    "test:watch": "vitest",
    "prepare": "husky install"
  }
}
```

### Benefits of Git Hooks

1. **Consistency**: Enforce code style and formatting
2. **Quality**: Catch bugs before they're committed
3. **Efficiency**: Fail fast, fix early
4. **Automation**: Reduce manual checks
5. **Team alignment**: Ensure everyone follows the same standards

---

## Summary

This git workflow provides a structured approach to development for the glyphdiff.com project:

- **Clear branching strategy** with defined purposes for each branch type
- **Conventional commits** for readable and automated changelogs
- **Code splitting guidelines** to keep MRs focused and reviewable
- **Comprehensive review process** to maintain code quality
- **Git hooks** to automate quality checks

Following this workflow will help the team:
- Develop features in parallel without conflicts
- Maintain a clean git history
- Catch issues early in the development process
- Ensure code quality and consistency
- Streamline the release process

For questions or suggestions about this workflow, please discuss with the team or create an issue in the project repository.