Commits

At Terra, we treat commit messages as a critical part of our documentation and communication strategy. Well-organized commits serve multiple important purposes:

• Create a readable history that helps team members understand why changes were made, not just what changed.
• Structured commits make it easier for teammates to identify which changes are related to specific features or bug fixes.
• When issues arise, organized commits allow us to quickly trace back through the project history to identify when and why a problem was introduced, making it easier to revert or fix problematic changes.

---

Types of Commits

Each commit message should start with a type followed by a forward slash and description. The forward slash format helps organize commits into folders for better project structure. Here are the accepted types and their meanings:

• feature/ 🚀
  Use this when you’re adding a new feature. Examples include adding a new custom post type, a new “load more” functionality, or a webhook.

• fix/ 🐛
  Use this for bug fixes. Most of the time, these will be QA items reported by a client, PM, or UX/UI team.

• hotfix/ 🔥
  Use this for quick fixes that go directly to production.

• style/ 🎨
  Use this for commits that modify styling and layout. These should include style references like c--card-b, c--cta-a, etc.

• refactor/ 🔄
  Use this for codebase refactoring. This includes changes like restructuring code, removing unnecessary classes, etc., without altering functionality.

• docs/ 📚
  Use this for any changes related to documentation. This is exclusively for documentation updates.

• revert/ ↩️
  Use this when reverting a previous commit. Include the commit hash and reason for the revert.

• build-testing/ 🧪
  Use this when you want to do testing for a specific build.

Additional Description Guidelines

• Link to ClickUp
  Always include a link to the relevant ClickUp task in the commit description. This helps in tracking the task associated with the changes.

• Breaking Changes
  Breaking changes are modifications that alter existing functionality in a way that may require changes in other parts of the codebase. If your commit introduces breaking changes, mention it explicitly in the description. Clearly state what has changed and what needs to be updated elsewhere.

Note

A brief description in the commit message is required. If there isn’t a ClickUp card, it’s fine to omit the link, but creating one beforehand is encouraged for documentation. Only include a “Breaking Changes” section if there are actual breaking changes.

Example Commit Messages

feature/add-new-custom-post-type-for-blog-articles 🚀
Added new post type to support blog articles.
Ticket: <ClickUp task link>.
Breaking Changes: Updated routing for blog posts.

fix/correct-alignment-issue-in-header 🐛
Fixed header alignment on mobile view.
Ticket: <ClickUp task link>.

hotfix/close-modal-bug 🔥
Fixed modal close button.
Ticket: <ClickUp task link>.

style/update-card-b-styling-for-consistency 🎨
Updated card style to match new design guidelines.
Ticket: <ClickUp task link>.

refactor/simplify-api-response-handling-logic 🔄
Refactored API response handling to improve performance and readability.
Ticket: <ClickUp task link>.

docs/update-readme-with-new-setup-instructions 📚
Updated setup instructions to include new environment variables.

revert/feature-add-new-custom-post-type ↩️
Reverted previous commit due to issues with deployment. Original commit hash: `abc123`.
Ticket: <ClickUp task link>.

build-testing/portable-text-issue 🧪
Testing build on netlify with portable text
Ticket: <ClickUp task link>.

---

FAQs

• If I need to add a new module only HTML and hardcoded, what type of commit should I set?

If you’re adding a new module that includes only HTML and is hardcoded, this still counts as a new feature. Use the feature type for the commit message.

• If I only make a component dynamic, is it a feature?

Yes, making a component dynamic involves adding new functionality, so it should be categorized as a new feature. Use the feature type for the commit message.

• Should I use fix for updating documentation with corrections?

No, corrections to documentation should use the docs type. The fix type is reserved for bug fixes in the codebase.

• What should I do if my commit includes both a new feature and a bug fix?

It’s recommended to split the changes into separate commits, each with its appropriate type. This helps maintain a clear and concise commit history.

Important

Always ensure your commit messages are clear and descriptive. Use the appropriate type for each change and avoid combining different types in one commit. Even someone unfamiliar with coding should be able to understand your commit messages, so always think from that perspective!