Zillowe Foundation

Commit Message Structure

[Optional Emoji] <Type>([Optional Scope]): <Subject>

# Examples:
✨ Feat(auth): Add password strength meter
🩹 Fix: Resolve infinite loading issue
♻️ Refactor(api): Simplify response handling

Components:

Emoji: Optional visual indicator (improves scanability)
Type: Required category identifier (e.g. Feat, Fix)
Scope: Optional context specifier in parentheses
Subject: Concise description in present tense (imperative mood)

Supported Types

Emoji	Type	Description	Example
🛠️	Build	Changes to build system, tools or dependencies	`🛠️ Build(webpack): Upgrade to version 5`
🚀	CI	CI/CD pipeline changes	`🚀 CI(github): Add linting workflow`
📚	Docs	Documentation only changes	`📚 Docs: Update API reference`
✨	Feat	New features or enhancements	`✨ Feat(user): Add profile customization`
🩹	Fix	Bug fixes	`🩹 Fix(auth): Resolve session timeout issue`
⚡	Perf	Performance improvements	`⚡ Perf(queries): Optimize database lookups`
♻️	Refactor	Code changes that neither fix bugs nor add features	`♻️ Refactor: Extract reusable components`
🎨	Style	Code style/formatting changes	`🎨 Style: Format according to style guide`
🧪	Test	Adding or updating tests	`🧪 Test(api): Add integration tests`
⏪	Revert	Revert previous changes	`⏪ Revert: Return to commit abc123`
🛡️	Deps	Manage dependencies (e.g. adding/removing libraries)	`🛡️ Deps: Remove unused Lodash methods`
🧹	Cleanup	Organize or remove unused code/files	`🧹 Cleanup: Remove unused CSS classes`
📦	Release	Prepare for a release (e.g. version bump, changelog updates)	`📦 Release: Prepare for v1.0.0`
🔒	Security	Security-related changes	`🔒 Security(auth): Implement rate limiting`
🌐	I18n	Internationalization/localization	`🌐 I18n: Add German translations`
➡️	Migrate	Major migrations or transitions	`➡️ Migrate: Convert to TypeScript`
🔍	SEO	Search engine optimization	`🔍 SEO: Improve meta tags`
🧠	AI	AI/ML model or algorithm changes	`🧠 AI: Update recommendation algorithm`
📊	Data	Data structure or content changes	`📊 Data: Update seed data`
🔧	Config	Configuration changes	`🔧 Config: Update environment variables`
🎯	UX	User experience improvements	`🎯 UX: Streamline checkout process`
🏗️	Struct	Project structure changes	`🏗️ Struct: Reorganize component hierarchy`
🔐	Auth	Authentication/authorization	`🔐 Auth: Add OAuth integration`
📈	Track	Analytics or tracking	`📈 Track: Add conversion events`
⏩	Merge	Merging branches or merge requests	`🤝 Merge: Branch 'dev' into 'main'`
📋	API	API-related changes	`📋 API: Add pagination to endpoints`
🔀	Git	Git structure and workflow changes	`🔀 Git(hooks): Update pre-commit validation`

Scopes (Optional but Recommended)

Scopes provide additional context about what part of the codebase is affected. Common scopes include:

Component names: header, footer, nav
Feature areas: auth, checkout, search
Technical domains: api, db, ui, ux
File types: css, js, tests

Best Practices

Use the imperative mood for the subject (e.g. "Add feature" not "Added feature")
Keep subjects concise (under 72 characters)
Be specific about what changes were made
No period at the end of the subject line
Use consistent emoji when applicable

Extended Commit Format (Optional)

For complex changes, you can add a body after the subject:

✨ Feat(auth): Add password strength meter

Implement zxcvbn library to provide real-time feedback on password strength.
- Displays color-coded strength indicator
- Shows improvement suggestions
- Prevents submission of weak passwords

Issue: #123

Example Workflow

Scenario: Adding a new feature and fixing related bugs

# Create a feature branch
git checkout -b feat/user-profiles

# Make changes to relevant files
git add src/components/UserProfile.js
git commit -m "✨ Feat(profile): Add user profile editor"

# Fix a bug discovered during implementation
git add src/utils/validation.js
git commit -m "🩹 Fix(validation): Resolve email format validation"

# Update documentation
git add README.md docs/api.md
git commit -m "📚 Docs(profile): Document profile endpoints"

# Push changes
git push origin feat/user-profiles

Automated Tools

Consider these tools to enforce ZFGM format:

commitlint: Validate commit messages against rules
commitizen: Interactive commit message builder
husky: Git hooks to validate before commit
gitmoji-cli: Streamline emoji usage

Advanced Tips

Co-authored commits: Add Co-authored-by: Name <email> at the end of the commit message body
Breaking changes: Mark with BREAKING CHANGE: in the commit body
Issue references: Include issue IDs in the commit body or footer

Commits