Git Commit Message Guidelines

Consistent Git commit messages make a project easier to review, maintain, debug, and release. A good commit message should explain what changed, where it changed, and ideally why the change was necessary.

This project follows a Conventional Commits-style format.

Commit Message Format

<type>(<scope>): <short description>

Example:

feat(invoice): add OCR-based invoice processing

Where:

• feat is the type of change
• invoice is the affected module or scope
• add OCR-based invoice processing is the concise description

The scope is optional, but strongly recommended for medium and large projects.

<type>: <short description>

Example:

docs: update installation instructions

---

General Rules

A commit message should:

• Use the imperative form
• Start with a lowercase description
• Avoid ending the subject with a period
• Clearly describe one logical change
• Remain concise, preferably under 72 characters
• Avoid vague messages such as update code, changes, or bug fixed
• Keep unrelated changes in separate commits

Write the message as though you are completing this sentence:

This commit will...

Good:

fix(auth): prevent expired tokens from accessing protected routes

This reads naturally:

This commit will prevent expired tokens from accessing protected routes.

Weak:

fixed token issue

---

Supported Commit Types

feat: New Feature

Use feat when introducing new functionality visible to users, administrators, API consumers, or another system.

Examples:

feat(auth): add two-factor authentication
feat(invoice): add OCR-based invoice processing
feat(profile): allow users to upload profile pictures
feat(api): add customer export endpoint
feat(admin): add role-based permission management
feat(payment): support Stripe webhook processing
feat(report): add monthly revenue summary
feat(search): add advanced property filters
feat(notification): send email after order completion
feat(ai): add document classification pipeline

Use feat for:

• New pages
• New API endpoints
• New commands
• New integrations
• New business workflows
• New AI or ML capabilities

---

fix: Bug Fix

Use fix when correcting incorrect, broken, or unexpected behavior.

Examples:

fix(auth): prevent expired tokens from accessing protected routes
fix(invoice): correct tax calculation for discounted items
fix(upload): handle filenames containing spaces
fix(api): return 404 when customer record is missing
fix(session): preserve login state after password update
fix(payment): prevent duplicate charges during retry
fix(report): correct timezone conversion in daily totals
fix(validation): reject malformed email addresses
fix(queue): retry failed email jobs correctly
fix(ai): handle empty OCR output without crashing

Avoid vague messages:

fix: bug fixed
fix: issue resolved
fix: small correction

Prefer:

fix(order): prevent duplicate order creation on form resubmission

---

refactor: Internal Restructuring

Use refactor when changing internal code structure without intentionally changing external behavior.

Examples:

refactor(admin): move validation logic into service layer
refactor(auth): extract token verification into dedicated class
refactor(order): replace duplicated calculations with shared helper
refactor(api): split customer controller into smaller actions
refactor(database): move complex queries into repository layer
refactor(invoice): replace nested conditions with strategy classes
refactor(model): simplify customer relationship definitions
refactor(ai): separate preprocessing from inference pipeline
refactor(config): centralize environment-specific settings
refactor(queue): isolate job retry logic

Do not use refactor when the change introduces a new feature or fixes a defect. Use feat or fix instead.

---

perf: Performance Improvement

Use perf when improving speed, memory usage, database efficiency, throughput, latency, or resource consumption.

Examples:

perf(api): reduce customer search query time
perf(database): add index for invoice status filtering
perf(order): remove N+1 queries from order history
perf(cache): cache frequently requested dashboard metrics
perf(image): reduce memory usage during thumbnail generation
perf(queue): batch notification jobs
perf(report): stream large CSV exports
perf(ai): batch embeddings during document indexing
perf(ml): reduce model inference latency
perf(frontend): lazy-load dashboard charts

A performance commit should ideally include measurable evidence.

Example commit body:

perf(api): reduce customer search query time

Replace repeated joins with a pre-aggregated query and add an index on
customers.status.

Average response time decreased from 820 ms to 190 ms on the staging dataset.

---

test: Test Changes

Use test when adding, updating, restructuring, or correcting tests without changing production behavior.

Examples:

test(auth): add expired-token test cases
test(invoice): cover discount and tax calculations
test(api): add validation tests for customer creation
test(payment): add duplicate webhook scenarios
test(upload): cover invalid file extensions
test(order): add integration tests for checkout workflow
test(database): add migration rollback tests
test(ai): add OCR pipeline regression tests
test(ml): add reproducibility tests for training pipeline
test(report): add timezone edge-case coverage

Do not use test when production code is also fixed. In that case, the main commit may use fix, with tests included in the same logical change.

---

docs: Documentation Changes

Use docs for documentation-only updates.

Examples:

docs: update local installation instructions
docs(api): document customer search endpoint
docs(auth): add token refresh examples
docs(deployment): add production rollback procedure
docs(database): explain migration workflow
docs(ai): document model evaluation process
docs(readme): add project architecture overview
docs(contributing): add Git commit guidelines
docs(security): document secret-management policy
docs(report): add export configuration examples

Documentation may include:

• README updates
• API documentation
• Architecture documents
• Code comments
• Setup guides
• Deployment instructions
• Contributor guides

---

security: Security Improvement

Use security when addressing vulnerabilities, reducing attack surface, strengthening authorization, or improving secure handling of data.

Examples:

security(upload): validate file MIME type and extension
security(auth): revoke refresh tokens after password reset
security(api): enforce authorization on customer endpoints
security(session): regenerate session ID after login
security(database): replace raw queries with parameter binding
security(config): remove hardcoded credentials
security/logging): prevent access tokens from appearing in logs
security/admin): restrict user deletion to super administrators
security/webhook): verify payment-provider signatures
security(ai): sanitize retrieved content before prompt construction

Security commits should avoid exposing sensitive exploit details in public repositories.

Weak:

security: fixed serious authentication vulnerability

Better:

security(auth): enforce ownership checks on profile updates

---

chore: Maintenance Work

Use chore for routine maintenance that does not directly affect application behavior.

Examples:

chore: update project dependencies
chore(ci): upgrade GitHub Actions versions
chore(config): add staging environment variables
chore(docker): update PHP base image
chore(deps): upgrade Laravel framework
chore(deps): update Python development packages
chore(git): update ignore rules
chore(build): remove obsolete build files
chore(release): prepare version 2.4.0
chore(cleanup): remove unused assets

Typical chore changes include:

• Dependency updates
• Build configuration
• CI/CD maintenance
• Repository cleanup
• Development tooling
• Release preparation

---

Recommended Additional Types

The following types are also useful for professional projects.

ci: Continuous Integration Changes

Use ci for CI/CD pipeline configuration.

Examples:

ci: run tests on PHP 8.3
ci(github): add Laravel test workflow
ci(gitlab): add deployment approval stage
ci(security): add dependency vulnerability scanning
ci(ai): cache model dependencies during builds

---

build: Build System Changes

Use build for changes affecting compilation, packaging, containers, or dependency management.

Examples:

build(docker): add production PHP image
build(vite): configure asset versioning
build(composer): optimize production autoloading
build(python): add wheel packaging configuration
build(ai): include model assets in release package

---

style: Formatting-Only Changes

Use style when changing formatting without changing behavior.

Examples:

style(php): apply PSR-12 formatting
style(python): format project with Black
style(view): align Blade template indentation
style(css): normalize spacing in dashboard components

Do not use style for visual UI design changes. A user-facing design change is usually a feat or fix.

---

revert: Reverted Change

Use revert when undoing a previous commit.

Examples:

revert: remove asynchronous invoice processing
revert(auth): restore previous token expiration logic

The commit body should reference the reverted commit.

revert: remove asynchronous invoice processing

Reverts commit 8f41c92 because queue processing caused duplicate invoice jobs.

---

Choosing an Effective Scope

The scope identifies the part of the application affected by the change.

Common scopes for Laravel and CodeIgniter projects:

auth
admin
api
invoice
payment
order
customer
upload
database
migration
queue
notification
report
session
validation
config
deployment

Common scopes for Python, AI, ML, and data-science projects:

data
etl
training
inference
evaluation
model
ocr
rag
embedding
retrieval
prompt
agent
api
notebook
pipeline
feature
experiment

Examples:

feat(rag): add hybrid document retrieval
fix(training): prevent validation data leakage
perf(inference): enable batched model predictions
test(data): add schema validation tests
docs(model): document intended use and limitations

Avoid scopes that are too broad:

fix(app): resolve issue

Prefer a specific scope:

fix(invoice): prevent duplicate PDF generation

---

Writing the Commit Description

The description should explain the direct result of the commit.

Good examples:

feat(auth): add passwordless email login
fix(payment): reject duplicate webhook events
refactor(order): move pricing logic into domain service
perf(report): cache monthly summary calculations
security(api): enforce tenant ownership checks

Weak examples:

update auth
payment changes
code cleanup
new updates
final fix
work completed

---

Commit Message With a Body

For small changes, the subject line may be enough.

For complex or high-risk changes, add a commit body.

Format:

<type>(<scope>): <short description>

Explain why the change was required and how it works.

Describe any risks, compatibility concerns, migrations, or side effects.

Refs: PROJECT-123

Example:

fix(payment): prevent duplicate transaction processing

Store the provider transaction ID before processing the payment result.
Subsequent webhook deliveries now return the existing transaction instead
of creating another charge record.

This protects against duplicate provider callbacks and retry events.

Refs: PAY-142

---

Breaking Changes

A breaking change modifies an existing public API, database contract, configuration format, or expected behavior.

Use an exclamation mark after the type or scope:

feat(api)!: replace customer response structure

Add a clear note in the commit body:

feat(api)!: replace customer response structure

Return customer details under a new data object and remove the deprecated
customer_name field.

BREAKING CHANGE: API consumers must read data.name instead of customer_name.

Additional examples:

feat(auth)!: require two-factor authentication for administrators
refactor(database)!: rename customer_id column to account_id
feat(config)!: replace legacy mail configuration variables

---

Git Commit Examples by Project Type

Laravel and CodeIgniter

feat(auth): add login attempt throttling
fix(session): regenerate session after authentication
feat(invoice): generate downloadable PDF invoices
fix(validation): preserve submitted values after form failure
refactor(controller): move invoice logic into service class
perf(database): add composite index for order lookup
test(api): add unauthorized-access test cases
docs(deployment): document queue worker restart process
security(upload): reject executable file signatures
chore(composer): update production dependencies

Python Application

feat(api): add batch prediction endpoint
fix(parser): handle malformed CSV rows
refactor(config): replace global settings with typed configuration
perf(worker): process input files concurrently
test(parser): add invalid-encoding scenarios
docs(cli): add command-line usage examples
chore(deps): update Python dependencies

AI and Machine Learning

feat(training): add class-weighted loss
fix(data): prevent train-test entity overlap
feat(evaluation): add per-class precision and recall
perf(inference): enable GPU batch prediction
refactor(model): separate encoder from classification head
test(pipeline): add reproducibility test with fixed seed
docs(model): document training dataset limitations
security(rag): block prompt instructions from retrieved documents
chore(experiment): archive outdated model checkpoints

Data Science

feat(analysis): add customer churn segmentation
fix(data): correct missing-value handling for income column
refactor(notebook): extract reusable preprocessing functions
perf(etl): vectorize transaction aggregation
test(data): validate required dataset columns
docs(report): explain confidence interval calculation
chore(notebook): remove unused exploratory cells

DevOps and AWS

feat(aws): add S3 lifecycle policy
fix(ecs): restore container health check
security(iam): restrict deployment role permissions
perf(cloudfront): enable static asset compression
ci(github): deploy staging after successful tests
build(docker): reduce production image size
chore(terraform): update AWS provider version
docs(runbook): add rollback instructions

---

Examples of Separating Unrelated Changes

Avoid combining unrelated work:

feat(auth): add two-factor authentication and update invoice styling

Split it into separate commits:

feat(auth): add two-factor authentication
style(invoice): update invoice layout spacing

Another weak example:

fix: update API, database, login, tests, and documentation

Better:

fix(api): return correct status for missing customer
perf(database): add customer email index
test(api): cover missing-customer response
docs(api): document customer error responses

---

Good Commit History Example

feat(invoice): add PDF generation service
feat(invoice): add invoice download endpoint
test(invoice): add PDF generation tests
security(invoice): restrict downloads to invoice owners
docs(invoice): document download endpoint

This history is easier to understand than:

invoice work
more changes
fix things
final
final fix
working now

---

Recommended Commit Workflow

Review your changes before committing:

git status
git diff
git diff --staged

Stage the relevant files:

git add app/Services/InvoiceService.php
git add tests/Feature/InvoiceTest.php

Commit the change:

git commit -m "feat(invoice): add PDF generation service"

For a commit with a detailed body:

git commit

Your editor will open so you can write:

fix(payment): prevent duplicate transaction processing

Store and validate the payment provider event ID before processing the event.

Duplicate callbacks now return the existing payment result instead of
creating another transaction.

Refs: PAY-142

---

Final Commit Checklist

Before creating a commit, confirm:

• The commit contains one logical change
• The type accurately describes the change
• The scope identifies the affected module
• The description is specific and concise
• The message uses imperative language
• Tests have been added or updated where required
• Debug code and temporary files are removed
• No passwords, tokens, keys, or secrets are included
• The commit does not include unrelated formatting changes
• Breaking changes are clearly documented
• The related ticket or issue is referenced when applicable

---

Quick Reference

feat:      introduce a new feature
fix:       correct a defect
refactor:  restructure code without changing behavior
perf:      improve performance or resource usage
test:      add or update tests
docs:      update documentation
security:  improve security or fix a vulnerability
chore:     perform routine maintenance
ci:        update CI/CD configuration
build:     update build or packaging configuration
style:     apply formatting-only changes
revert:    undo a previous commit

Examples:

feat(invoice): add OCR-based invoice processing
fix(auth): prevent expired tokens from accessing protected routes
refactor(admin): move validation logic into service layer
perf(api): reduce customer search query time
test(payment): add duplicate webhook scenarios
docs(api): document customer export endpoint
security(upload): validate file MIME type and extension
chore(deps): update framework dependencies
ci(github): run tests before deployment
build(docker): reduce production image size