glyphdiff.com/frontend-svelte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
98febdc24c451dbc8a7fd1fe6e6467d42e9f515e
frontend-svelte/docs/GIT_WORKFLOW.md

15 KiB
Raw Blame History

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
  2. Branch Naming Conventions
  3. Commit Message Conventions
  4. Code Splitting and Merge Request Guidelines
  5. Branch Protection Rules
  6. 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 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:

## 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
  5. Merge: Squash and merge into target branch
  6. 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:

#!/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:

# 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:

#!/bin/sh
# .git/hooks/commit-msg

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

Setup:

# 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:

#!/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:

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

Alternative: Using Husky

Husky is a popular tool for managing git hooks. It's easier to maintain and works across different operating systems.

Installation:

npm install --save-dev husky
npx husky install
npm pkg set scripts.prepare="husky install"

Adding hooks:

# 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:

{
  "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.

Reference in New Issue View Git Blame Copy Permalink