Coding Conventions

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.

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. Indentation corrected. Removed white spaces. Added missing semi-colons.
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.. Changed the enigmatic function’s name by meaningful names. Changed an algorithm code for a more efficient one delivering the same result as before. Split code into several files to reduce lines of code for help to decouple. Removing commented code. Removing code duplication by making a unique and reusable function.
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!

Blog

Daniel Guglielmi

Table of Contents