# Commit messages

*Published:* 2025-11-27
*Author:* Sayed Taqui

> Establish consistent Git workflow with semantic commit messages, branching strategies, and clear Pull Request (PR) guidelines.

# Commit messages

While commit messages are not React-specific, they are crucial for maintaining a **clean and understandable project history**. Clear commit messages and PR conventions improve collaboration, make debugging easier, and speed up code reviews.

As we currently lack a general best practices guide, these guidelines will serve as a placeholder and can be moved to the broader document when available.

## 1. Be concise yet descriptive

- The subject line should summarize the change in **50 characters or less**.
- Avoid vague phrases like “fixed stuff” or “updated code.”

## 2. Use imperative mood

When writing commit messages, use the imperative mood. This means phrasing the subject line as if you’re giving a command. This style aligns with Git’s approach because commit messages describe what applying the commit will do, not what has been done.

A well-formed Git commit subject line should complete this sentence

“If applied, this commit will…”

- ✅ Add unit tests for login functionality
- ❌ Added unit tests for login functionality

## 3. Add context in the body (optional)

If the change is complex, include a brief explanation in the body.

- What was changed and why.
- Mention trade-offs or limitations..
- Include bullet points for better readability.
- Reference related issues in the footer (e.g., Closes #123).

Example

```
Resolve crash when editing user details- Fix null reference error when editing without selecting a role- Add default role assignment for new usersCloses #123
```

**Other Points:**

- Capitalize the subject line.
- Do not end the subject line with a period.

## Bad commit messages: ❌

**Too vague:** These messages are too generic and don’t describe what was changed, why, or where.

- Fixed stuff
- Made changes
- Update code
- Bug fixed
- fixed: login

**Too long:** Commit messages should be concise. This message is overwhelming and doesn’t follow the 50-character rule for the subject line.

- ❌ Refactored the entire codebase to improve performance by rewriting major parts of the backend authentication module and fixing various bugs in the process while also updating the documentation for developers.

**Unprofessional:** These messages are unprofessional and provide no meaningful information about the commit.

- Fixing this for the last time, I swear
- I have no idea why this works but okay

**Written in the future tense:** Commit messages describe what was done, not what will be done. Future tense is misleading and unnecessary.

- Will add new login feature
- Will fix logout issue

Commit examples from some known developers to us

- [Dan](https://github.com/facebook/react/commits?author=gaearon)
- [Paul](https://github.com/facebook/react/commits?author=zpao)
- [Aron Jorbin](https://github.com/WordPress/gutenberg/pull/32700/commits)
- [Riad Benguella](https://github.com/WordPress/gutenberg/pull/67393/commits)
- [Weston Ruter](https://github.com/WordPress/performance/pull/1713/commits)
- [Amoghavarsha Kudaligi](https://github.com/GoogleChromeLabs/ps-analysis-tool/commits?author=amovar18)
- [Mayank Rana](https://github.com/GoogleChromeLabs/ps-analysis-tool/commits?author=mayan-000)

## PR titles

When writing PR titles, we follow most of the same principles used for writing good commit subject lines. Specifically, we aim to:

1. Be concise yet descriptive.
2. Use an imperative mood.
3. Capitalize the subject line.
4. Avoid ending the subject line with a period

Example

✅ Fix crash on login page when username is empty

Additional consideration for PR titles are as follows

### Keep it short and focused

Limit to 50-70 characters if possible and provide **additional details** in the PR description, not the title.

Example

✅ Refactor user profile component for better readability

❌ Refactored the entire user profile component and removed old code for improved readability and maintainability

### Include context or scope

Mention the area of the codebase or feature the PR affects.

Example

✅ Update API response handling for payment gateway

❌ Update API response handling

### Avoid abbreviations and jargon

Use plain language to ensure clarity.

Example

✅ Improve error handling for user registration API

❌ Fix ERR#123 in reg API

### Common formats

We may follow the following formats for better clarity to some PR titles.

\[Type/Action/Area/Feature\]: \[Feature/Change/Issue\]

- Feature: Add user authentication flow
- Fix: Resolve issue with image upload failing on iOS
- Refactor: Optimize database queries for faster load times

- Login Page: Fix typo in error message
- Dashboard: Add filter for user roles

#### Avoid using format prefixes when not required

Don’t use structured prefixes (like Feature, Fix, etc.) if they don’t add clarity to the PR title. Instead, focus on making the title concise, human-readable, and reflective of the PR’s purpose. While structured formats such as \[Type/Action/Area/Feature\] can make PR titles more consistent, forcing them for every PR can lead to redundancy, confusion, or bloated titles. Sometimes, a straightforward, human-readable title works better.

Examples

**Trivial or minor changes:** Some changes are too small to warrant a structured format.

Bad (Unnecessary Prefix): ❌

- Refactor: Remove unused import
- Feat: Fix typo in a comment
- Fix: Update README formatting
- Refactor: Update .gitignore

**Multi-area or cross-cutting changes:** If the PR spans multiple unrelated areas, using a prefix can mislead reviewers into thinking the change is scoped to a single area.

Bad (Unnecessary Prefix): ❌

- Feat: Update dashboard and fix login flow
- Fix: Change settings and update database schema

### Example of bad PR titles ❌

- Changes made (Generic title)
- Improve performance (Ambiguous title)
- Updated the user profile page and fixed a bug that caused the app to crash when users clicked on the save button while editing their profile, and also improved performance on the settings page. (Too long)
- Add info tab to Bottom table ( Improper capitalization )

## PR description

A Pull Request description should not be written in the past tense because it describes the **current state** of the PR, it represents changes that are being **proposed**, reviewed, and merged, rather than something already completed or finalized. Therefore it should be written in a **declarative tone** for example

- ✅ This PR adds user authentication functionality to enable secure logins using OAuth2
- ❌ Added user authentication functionality.

We should create a template for PR description as per the need of the project. Here is our preferred PR template.

```
## Description<!-- What do we want to achieve with this PR? -->## Relevant Technical Choices<!-- For Code Reviewers: Please describe your changes. -->## Testing Instructions<!-- For someone doing QA: How can the changes in this PR be tested? Please provide step-by-step instructions to test the changes. -->## Additional Information:<!-- Include any other context, links, or references that reviewers or QA should be aware of. -->## Screenshot/Screencast<!-- Add visual aids to demonstrate the changes made in this PR, if applicable. -->## Checklist<!-- Check these after creating PR, use NA if something is not applicable -->- [ ] I have carefully reviewed the code before submitting it for review.- [ ] This code is adequately covered by unit tests to validate its functionality.- [ ] I have conducted thorough testing to ensure it functions as intended.- [ ] A member of the QA team has reviewed and tested this PR (To be checked by QA or code reviewer)<!--Example:Fixes #123Partially addresses #22See #834-->Fixes #
```

## Git branch naming

To maintain consistency and clarity across the team, we follow these rules for naming Git branches:

**1. Use a clear and consistent structure**

Adopt a structured format to make branch names meaningful and easy to understand. A common structure is:

\[type\]/\[short-description\]

**2. Use lowercase letters only**

Examples:

- ✅ feat/add-user-auth
- ✅ fix/login-issue

**3. Use hyphens to separate words**

Examples:

- ✅ feat/add-user-auth
- ❌ feat\_add\_user\_auth

**4. Begin with a prefix for the branch type**

- feat/: New features
- fix/: Bug fixes
- ref/: Refactors (no behavior change)
- chore/: Non-functional tasks (dependencies, configs)
- docs/: Documentation changes
- test/: Adding or modifying tests
- release/: Preparing a release (e.g., release/v0.2.1)
- perf/: Performance improvements
- revert/: Reverting commits
- security/: Security patches
- try/: Experimental work, not for merging
- add/: Introducing small files/components/assets

**Things to avoid:**

- Use a brief yet descriptive name
    - Do: feat/add-search-bar
    - Avoid: feat/added-a-new-search-bar-that-works-with-filters
- Avoid special characters
    - Do: docs/update-readme
    - Avoid: docs/update@readme
- Avoid redundant information
    - Do: fix/logout-crash
    - Avoid: fix/logout-crash-task

### Categories and Taxonomies

#### Service
[WP React Development](https://rtcamp.com/blog/service/wp-react-development.md)

#### Solutions
[WordPress Development](https://rtcamp.com/blog/solution/wordpress-development.md)

#### Topics
[Frontend](https://rtcamp.com/topics/frontend.md), [WordPress](https://rtcamp.com/topics/wordpress.md), [WordPress Development](https://rtcamp.com/topics/wordpress-development.md)

### Related Posts

- [Structural Limits of Accounting-First Software](https://rtcamp.com/handbook/why-migrate-quickbooks-to-erpnext/structural-limits.md)
- [Project structure](https://rtcamp.com/handbook/react-best-practices/project-structure.md)
- [Outgrowing standard hosting](https://rtcamp.com/handbook/enterprise-wordpress-hosting/why-choose-enterprise-wordpress-hosting.md)
- [WordPress vs Kentico](https://rtcamp.com/handbook/enterprise-consolidation/kentico-vs-wordpress.md)
- [rtCamp’s philosophy & principles](https://rtcamp.com/handbook/headless-wordpress/rtcamps-philosophy.md)
