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 users
Closes #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
PR titles
When writing PR titles, we follow most of the same principles used for writing good commit subject lines. Specifically, we aim to:
- Be concise yet descriptive.
- Use an imperative mood.
- Capitalize the subject line.
- 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 #123
Partially addresses #22
See #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 featuresfix/: Bug fixesref/: Refactors (no behavior change)chore/: Non-functional tasks (dependencies, configs)docs/: Documentation changestest/: Adding or modifying testsrelease/: Preparing a release (e.g.,release/v0.2.1)perf/: Performance improvementsrevert/: Reverting commitssecurity/: Security patchestry/: Experimental work, not for mergingadd/: 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
