Semantic Commit Cheatsheet

[abenteuerzeit]

Style Guide

Semantic commits are a best practice for writing clear and informative commit messages that follow a standardized format. These commits make it easier for developers to understand the purpose and impact of each commit, facilitating collaboration and code maintenance. In this cheatsheet, a comprehensive reference guide on how to write semantic commits using the conventional format is presented.

Commit Types

Start by selecting a commit type that best describes the nature of the changes made. Choose the appropriate type from the table below:

Type	Description	Emoji (optional)	Helping Questions
feat	Introduce a new feature or enhancement	✨	Is this commit introducing a new feature or enhancement? Does this commit add new functionality to the application? Is this commit implementing a feature discussed in the project's discussions or issues?
fix	Fix a bug or error	🐛	Is this commit fixing a bug or error in the application? Does this commit resolve an issue reported by a user or found during testing? Is this commit addressing a problem discussed in the project's discussions or issues?
docs	Update or add documentation	📚	Is this commit updating or adding to the project's documentation? Does this commit provide additional information or clarification about the project or its features? Is this commit addressing a documentation need discussed in the project's discussions or issues?
style	Perform code style/formatting changes	💅	Is this commit making changes to the code's style or formatting? Does this commit improve the readability or consistency of the code? Is this commit addressing a style or formatting issue discussed in the project's discussions or issues?
refactor	Make code changes that neither fix a bug nor add a new feature	♻️	Is this commit making changes to the code that don't fix a bug or add a new feature? Does this commit improve the structure or efficiency of the code? Is this commit addressing a refactoring need discussed in the project's discussions or issues?
test	Add or modify tests	✅	Is this commit adding or modifying tests for the application? Does this commit improve the coverage or effectiveness of the project's tests? Is this commit addressing a testing need discussed in the project's discussions or issues?
chore	Update build tasks, dependencies, or other non-code-related tasks	🧹	Is this commit updating build tasks, dependencies, or other non-code-related tasks? Does this commit improve the project's build process, update its dependencies, or handle another non-code-related task? Is this commit addressing a chore discussed in the project's discussions or issues?

Examples:

feat(rating): Add landlord rating feature ✨

This commit introduces a new feature that allows users to rate landlords. This feature was discussed in the project's discussions and is expected to enhance the user experience by providing valuable information about landlords.

fix(rating): Fix bug in landlord rating feature 🐛

This commit fixes a bug in the landlord rating feature that was causing incorrect ratings to be displayed. This bug was reported in the project's discussions and its resolution is expected to improve the accuracy of the landlord ratings.

chore(testing): Implement Test-Driven Development (TDD) methodology 🧹

This commit implements the Test-Driven Development (TDD) methodology in the project, as discussed in the project's discussions. This change is expected to improve the quality of the code and facilitate the detection and resolution of bugs.

test(frontend): Add unit tests for React components ✅

This commit adds unit tests for

the React components in the frontend of the application. These tests were discussed in the project's discussions and are expected to ensure the correct functioning of the components.

Providing a Scope (optional)

If the commit affects a specific component or module within the TenantTalk project, provide a scope to indicate which part of the project is impacted. The scope should be a short descriptor of the component or module affected. For example, if your changes are related to the user authentication system, you might use auth as the scope.

Helping Questions for Scope:

• Does this commit affect a specific component or module within the project?
• Can the changes made in this commit be grouped under a specific part of the project?
• Would specifying a part of the project help other developers understand the context of the changes?

Examples:

feat(auth): Implement JWT-based user authentication ✨

This commit introduces a JWT-based user authentication system in the 'auth' module of the project. This feature was discussed in the project's discussions and is expected to enhance the security and user experience of the application.

fix(ui): Resolve layout bug in the user dashboard 🐛

This commit fixes a layout bug in the user dashboard component of the UI module. This bug was reported in the project's discussions and its resolution is expected to improve the user interface of the application.

Writing a Short Description

Write a concise summary of the changes made. Begin with a present-tense verb and use sentence case. The short description should be a brief summary of the changes, ideally not exceeding 50 characters.

Helping Questions for Short Description:

• Can you summarize the changes made in this commit in one sentence?
• What is the main action performed by this commit?
• If you had to describe this commit to another developer in a few words, what would you say?

Examples:

feat(auth): Implement JWT-based user authentication ✨

This commit introduces a JWT-based user authentication system in the 'auth' module of the project.

fix(ui): Resolve layout bug in the user dashboard 🐛

This commit fixes a layout bug in the user dashboard component of the UI module.

Adding Additional Details (optional)

If needed, provide additional context or details about the changes made. This can include the reasoning behind the changes, the impact of the changes, or any other relevant information that would help other developers understand the commit.

Helping Questions for Additional Details:

• Why were these changes made?
• What is the expected impact of these changes?
• Is there any other information that would help other developers understand these changes?

Examples:

feat(auth): Implement JWT-based user authentication ✨

This commit introduces a JWT-based user authentication system in the 'auth' module of the project. This system includes registration, login, and password reset functionality, ensuring that users can securely access and interact with the application's features.

fix(ui): Resolve layout bug in the user dashboard 🐛

This commit fixes a layout bug in the user dashboard component of the UI module. This bug was causing the dashboard layout to break on smaller screen sizes, and its resolution is expected to improve the responsiveness and user experience of the application.

Referencing Issues (optional)

If the commit is related to a specific issue or task tracked in an issue tracking system, reference it by including the issue number or ID. This can help link the commit to the relevant discussion or task, providing additional context and facilitating tracking of project progress.

Helping Questions for Referencing Issues:

• Is this commit related to a specific issue or task in the issue tracking system?
• Would linking this commit to an issue or task provide additional context or help track project progress?
• Is there a discussion or task in the project's discussions or

issues that this commit is addressing or related to?

Examples:

feat(auth): Implement JWT-based user authentication ✨

This commit introduces a JWT-based user authentication system in the 'auth' module of the project. This system includes registration, login, and password reset functionality, ensuring that users can securely access and interact with the application's features.

Closes #123

fix(ui): Resolve layout bug in the user dashboard 🐛

This commit fixes a layout bug in the user dashboard component of the UI module. This bug was causing the dashboard layout to break on smaller screen sizes, and its resolution is expected to improve the responsiveness and user experience of the application.

Closes #456

FAQ

Q: What if my changes include multiple types?

If your changes involve multiple types (e.g., introducing a new feature and fixing a bug), it's recommended to split them into separate commits, each focusing on a specific type of change. This helps keep the commit history clear and allows for better tracking of changes.

Q: Can I add my own commit types or emojis?

While the provided commit types and emojis cover common scenarios, you can customize them to better suit your project's needs. Ensure that the commit types and emojis remain consistent across the team to maintain clarity and avoid confusion.

Q: Is providing a scope always necessary?

Providing a scope is not always necessary, but it can be helpful in providing additional context about the changes made. If the commit affects a specific component or module within the project, it's beneficial to include a scope.

Q: What are the benefits of using semantic commit messages?

Semantic commit messages can help in conveying complex information simply. They set the stage, frame the issues, and provide detailed analysis that feeds into the larger decision-making process. They also help in independent development, making correctness proofs easier to derive, increasing potential reusability, reducing maintenance costs, and making the code less error-prone.

Q: What are the common mistakes to avoid when writing commit messages?

Common mistakes to avoid when writing commit messages include not providing a clear and concise summary of the changes made, not using the present tense, not including a scope when necessary, and not referencing related issues or tasks. It's also important to avoid writing commit messages that are too long or too short, as they may not provide enough context or detail about the changes made.

The goal of a commit message is to provide clear, concise, and relevant information about the changes made. It should be easy to understand and provide enough context for anyone reading it to understand the purpose and impact of the changes. Ko

[abenteuerzeit]

Merging #5 as the request for review has timed out.

Reviewers:

• @DemetrPI
• @LucidMoments
• @Efzo
• @piotrpalacz

Kindly review the changes to ensure you're up-to-date.

On a related note, I recently merged pull request #10, which contained a substantial number of changes bundled into single commits. Moving forward, I'd like to emphasize the importance of crafting atomic commits for each distinct change. By keeping your changes small and distinct, we can enhance code reviews, ease browsing through the history, and simplify reverting changes when needed.

For instance, if you install a new package, that action should constitute its own commit. I recommend using Git's interactive mode (git add -i or git add --interactive) or patch approach to break your changes into smaller, manageable commits. This practice not only reduces the chances of errors, but also simplifies the process of understanding what each commit does.

Before you commit, you can use git diff --cached to check what you're committing. This can help you make sure that your commit only includes the intended changes.

If you're unfamiliar with atomic commits, consider this your homework. Please refer to the resources I've shared and make sure you understand how to apply these principles in your work. Maintaining an organized and clear commit history is crucial for the productivity of our team, and it's a responsibility we all share.

Thank you for your cooperation and commitment to improving our development practices.

Docs

1. How To Craft Your Changes Into Small Atomic Commits Using Git - Small, atomic commits make it easier for code reviews, browsing the history, and reverting changes.
2. Atomic Commits Best Practice - Stack Overflow - Smaller commits are always better than longer ones. But you could question How small? I would use the following philosophy: If you can describe what you did in this commit in a short sentence, and it makes sense, commit.