This document provides comprehensive guidelines to foster alignment in development practices within the team. It encompasses various topics including the application of Semantic Versioning, branch naming conventions, different types of commits, and best practices for composing commit comments. The guide incorporates illustrative examples of both exemplary and subpar comments, serving as a valuable resource to promote consistency and maintain high-quality standards.
Table of Contents
- Semantic Versioning
- How to Update the Version
- Branch Naming Convention
- Type of Commits
- Git-commit-msg-linter
- Bad and Good comments example
Semantic Versioning
| Version Format | Description |
|---|---|
| 1.0.0-alpha | May does not contain all of the features that are planned for the final version. |
| 1.0.0-beta | Feature complete, may have bugs, it is useful for demonstration and preview |
| 1.0.0-rc | (Release Candidate) - ready to release unless significant bugs emerge. All product features have been designed, coded, and tested. No known showstopper-class bugs. |
| 1.0.0-stable | The last 'RC' has passed all verifications/tests. |
How to Update a new Version
Branch Naming Convention
In order to adhere to the development team's branch naming convention, we will provide the following guidelines: Branch names must consist of the work type, the Jira ticket number, and a concise, descriptive name that accurately represents the addressed issue.
That being said, we will now provide a few examples of branch naming to further illustrate the guidelines:
Branch name structure:
<ProblemType>/<JiraTicket#>/<ShortDescriptiveName>
- Feature/TK-XXX/problem-to-solve
- Hotfix/TK-XXX/name-of-the-issue
- Bug/TK-XXX/bug-to-fix
- Rollback/TK-XXX/rollback-release-v1.0.0
- Defect/TK-XXX/defect-to-correct
- Spike/TK-XXX/spike-to-solve
- Refactor/TK-XXX/enhancement-in-the-project
You can find the full list of Problem Type in the next section (Type of Commits) column Problem Type.
Type of Commits
Depending on the type of commit, we will use the second column for commit messages.
Ex.: git commit -m “feat(TK-1234): add the comment for this commit"
| Problem Type | Short Type | Description |
|---|---|---|
| Feature | feat | New feature to our project. |
| Fixes | fix | Bug fixing. |
| Documentation | docs | Documentation only changes |
| Styles | style |
Changes that do not affect the meaning of the code.
|
| Refactors | refactor | Code changes don’t affect the behavior of any feature. We are not adding a new feature, we’re just improving the existing code, being sure that we are not modifying the result of a function, method, etc..
|
| Tests | test | Adding missing tests or correcting existing ones to the project. |
| Chores | chore | The commit includes a technical or preventative maintenance task that is necessary for managing the product or the repository, but it is not tied to any specific feature or user story. For example, releasing the product can be considered a chore. Regenerating generated code that must be included in the repository could be a chore. |
| Performance | perf | A code change that improves performance. |
| CI | ci | Changes to your CI configuration files and scripts. |
| Build | build | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
| Temp | temp | Temporary commit that won't be included in your CHANGELOG. |
| Remove | remove | The commit removes a feature from the product. Typically features are deprecated first for a period of time before being removed. Removing a feature from the product may be considered a breaking change that will require a major version number increment. |
| Revert | revert | The commit reverts one or more commits that were previously included in the product, but were accidentally merged or serious issues were discovered that required their removal from the main branch. |
| Security | security | The commit improves the security of the product or resolves a security issue that has been reported. |
Git-commit-msg-linter
This extension serves as a valuable tool to ensure that we adhere to the correct format when writing commit messages. You can easily download it from NPM Git Commit Msg Linter.
How to Install
$npm install git-commit-msg-linter --save-dev
Below you will find a short explanation of how to write these commit messages:
We will use the scope to specify the Jira Ticket number in our commit message.
Comments on git commit -m
| Comments | Wrong/Good |
|---|---|
| docs: Documentation updates |  |
| docs(TK-XXX): add documentation for new API endpoints to improve developer experience |  |
| feat: New feature added | |
| feat(TK-XXX): Implement OAuth2 authentication for user login to enhance security and improve user experience | |
| fix: Bug fixes | |
| fix(TK-XXX): Fixed issue with form validation for registration process to prevent invalid user registrations | |
| style: UI updates | |
| style(TK-XXX): Updated CSS for consistent styling across the website and improve usability | |
| chore: Maintenance updates | |
| chore(TK-XXX): Updated deployment process for better scalability and maintainability of the application | |
The comment should answer 2 questions:
- WHAT changed?
- WHY did it change?
The objective behind crafting comments in this manner is to produce succinct and streamlined messages, resulting in cleaner and more legible commit messages.
In conclusion, this document provides a comprehensive guide to some of the Coding Conventions used on a daily basis. I hope you find it both informative and practical, serving as a valuable resource for maintaining good coding practices. Should you have any further questions or require additional assistance, please don't hesitate to reach out. Happy coding!
Top comments (1)
This is excellent work, especially because when starting a project, it takes a long time to lay the groundwork for these conventions, thanks for sharing.