fse-git-workflow

name	fse-git-workflow
description	Guide for committing to Oh My Brand! using Conventional Commits, Husky hooks, and linting. Use this when making commits, pushing to remote, or fixing pre-commit linting failures.
metadata	{"author":"Wesley Smits","version":"1.0.0"}

FSE Git Workflow

Git workflows, Conventional Commits, Husky pre-commit hooks, and CI/CD for the Oh My Brand! FSE theme.

---

When to Use

• Making commits to the repository
• Creating feature branches
• Fixing pre-commit linting failures
• Understanding CI/CD pipeline requirements
• Creating pull requests
• Releasing new versions

---

Reference Files

File	Purpose
ci.yml	GitHub Actions CI workflow
PULL_REQUEST_TEMPLATE.md	PR template

---

Development Workflow

Initial Setup

# Clone and install
git clone [e-mail]:WesleySmits/oh-my-brand-wp-fse.git
cd oh-my-brand-wp-fse
pnpm install && composer install
pnpm run prepare

# Verify
pnpm run lint && pnpm test && composer test

Daily Flow

# 1. Start from main
git checkout main && git pull origin main

# 2. Create feature branch
git checkout -b feature/gallery-lightbox

# 3. Develop with watch mode
pnpm run watch

# 4. Lint and test before commit
pnpm run lint:fix && pnpm test && composer test

# 5. Commit (triggers hooks)
git commit -m "feat(gallery): Add lightbox functionality"

# 6. Push and create PR
git push -u origin feature/gallery-lightbox

---

Environment Commands

Command	Purpose
pnpm run build	Production build
pnpm run watch	Development watch mode
pnpm run lint	Run all linters
pnpm run lint:fix	Fix linting issues
pnpm test	Run JS/TS tests
pnpm run test:e2e	Run E2E tests
composer test	Run PHP tests
composer lint:fix	Fix PHP issues

---

Conventional Commits

Format

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

[optional body]

[optional footer(s)]

Commit Types

Type	Description	Example
feat	New feature	feat(gallery): Add zoom functionality
fix	Bug fix	fix(faq): Resolve accordion collapse issue
docs	Documentation only	docs(readme): Update installation steps
style	Formatting, CSS (no logic)	style(css): Fix BEM class indentation
refactor	Code refactoring	refactor(carousel): Simplify state
perf	Performance improvement	perf(images): Implement lazy loading
test	Adding/updating tests	test(gallery): Add navigation tests
build	Build system or deps	build(vite): Upgrade to version 6.1
ci	CI configuration	ci(github): Add e2e job
chore	Maintenance tasks	chore(deps): Update dependencies

Scopes

Scope	Use For
blocks	Block-related changes
gallery, faq, hero, etc.	Specific block
theme	Theme configuration
assets	CSS/JS assets
deps	Dependencies
ci	CI/CD

Subject Rules

Rule	Requirement
Case	Sentence case (capitalize first letter)
Empty	Subject cannot be empty
Full stop	No period at the end
Max length	Header max 100 characters

---

Branch Naming

Format

<type>/<description>

Type	Use For	Example
feature/	New features	feature/gallery-lightbox
fix/	Bug fixes	fix/carousel-navigation
docs/	Documentation	docs/update-readme
refactor/	Code refactoring	refactor/optimize-helpers
test/	Test additions	test/add-faq-tests
chore/	Maintenance	chore/update-dependencies

---

Git Hooks (Husky)

Hook: pre-commit

Runs lint-staged on staged files:

• ESLint for *.ts, *.js, *.tsx, *.jsx
• Stylelint for *.css
• PHPCS for *.php
• Prettier for formatting

Hook: commit-msg

Validates commit message format with commitlint.

What Happens When You Commit

1. pre-commit runs lint-staged on staged files
2. commit-msg validates message format
3. ✅ All pass → Commit succeeds
4. ❌ Any fail → Commit aborted, fix errors and retry

Reinstall Hooks

rm -rf .husky/_
pnpm run prepare

---

Pre-Commit Checklist

• pnpm run lint passes
• pnpm run lint:fix applied
• pnpm test passes
• composer test passes
• Commit message follows Conventional Commits
• Branch is up-to-date with main

---

Pull Request Process

1. Push branch to remote
2. Create PR on GitHub from feature branch to main
3. Fill template (see PULL_REQUEST_TEMPLATE.md)
4. CI runs - all checks must pass
5. Request review from maintainer
6. Squash merge to main after approval

PR Best Practices

Practice	Description
Small PRs	Keep changes focused
Descriptive titles	Use Conventional Commit format
Link issues	Reference related GitHub issues
Add screenshots	For visual changes

---

CI/CD Pipeline

Pipeline Jobs

See ci.yml for the full workflow.

Job	Purpose
commitlint	Validate commit messages
lint-js	ESLint + Stylelint
lint-php	PHPCS with WordPress standards
test-unit-js	Vitest with coverage
test-unit-php	PHPUnit
test-e2e	Playwright with wp-env
build	Production build verification

Required Status Checks

All checks must pass before merging:

• ✅ commitlint
• ✅ lint-js
• ✅ lint-php
• ✅ test-unit-js
• ✅ test-unit-php
• ✅ test-e2e
• ✅ build

---

Release Process

Semantic Versioning

MAJOR.MINOR.PATCH

MAJOR → Breaking changes
MINOR → New features (backward compatible)
PATCH → Bug fixes (backward compatible)

Creating a Release

# 1. Ensure main is up to date
git checkout main && git pull origin main

# 2. Update version in: style.css, package.json, functions.php

# 3. Update CHANGELOG.md

# 4. Commit version bump
git commit -m "chore(release): Bump version to 1.2.0"

# 5. Create and push tag
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin main --tags

# 6. Create GitHub release

---

Troubleshooting

Commit Message Errors

"type must be one of..."

# ❌ Wrong
git commit -m "added new button block"

# ✅ Correct
git commit -m "feat(blocks): Add new button block"

"subject must be sentence-case"

# ❌ Wrong
git commit -m "feat(gallery): add lightbox"

# ✅ Correct
git commit -m "feat(gallery): Add lightbox"

Lint Errors

# Fix all linting issues
pnpm run lint:fix

# Fix PHP issues
composer lint:fix

# Stage fixes and retry
git add . && git commit -m "feat(blocks): Add feature"

Git Hook Issues

# Reinstall hooks
rm -rf .husky/_
pnpm run prepare

Bypass Hooks (Emergency Only)

git commit -m "fix(urgent): Emergency fix" --no-verify
# Note: CI will still run all checks

---

Related Skills

• vitest-testing - JS testing
• phpunit-testing - PHP testing
• playwright-testing - E2E testing

---

References

• Conventional Commits Specification
• Commitlint Documentation
• Husky Documentation
• Semantic Versioning