Coding Conventions
Published: 2023-06-07 15:17:16

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

![How and when to change the version number](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zl4k9yyeksr3tjk19lqs.png)

-------

## 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"`

<table>
<tr>
<th>Problem Type</th>
<th>Short Type</th>
<th>Description</th>
</tr>
<tr>
<td><b>Feature</b></td>
<td>feat</td>
<td>New feature to our project.</td>
</tr>
<tr>
<td><b>Fixes</b></td>
<td>fix</td>
<td>Bug fixing.</td>
</tr>
<tr>
<td><b>Documentation</b></td>
<td>docs</td>
<td>Documentation only changes</td>
</tr>
<tr>
<td><b>Styles</b></td>
<td>style</td>
<td>
Changes that do not affect the meaning of the code.
<ul>
<li>Indentation corrected.</li>
<li>Removed white spaces.</li>
<li>Added missing semi-colons.</li>
</ul>
</td>
</tr>
<tr>
<td><b>Refactors</b></td>
<td>refactor</td>
<td>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..
<ul>
<li>Changed the enigmatic function’s name by meaningful names.</li>
<li>Changed an algorithm code for a more efficient one delivering the same result as before.</li>
<li>Split code into several files to reduce lines of code for help to decouple.</li>
<li>Removing commented code.</li>
<li>Removing code duplication by making a unique and reusable function.</li>
</ul>
</td>
</tr>
<tr>
<td><b>Tests</b></td>
<td>test</td>
<td>Adding missing tests or correcting existing ones to the project.</td>
</tr>
<tr>
<td><b>Chores</b></td>
<td>chore</td>
<td>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.</td>
</tr>
<tr>
<td><b>Performance</b></td>
<td>perf</td>
<td>A code change that improves performance.</td>
</tr>
<tr>
<td><b>CI</b></td>
<td>ci</td>
<td>Changes to your CI configuration files and scripts.</td>
</tr>
<tr>
<td><b>Build</b></td>
<td>build</td>
<td>Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)</td>
</tr>
<tr>
<td><b>Temp</b></td>
<td>temp</td>
<td>Temporary commit that won't be included in your CHANGELOG.</td>
</tr>
<tr>
<td><b>Remove</b></td>
<td>remove</td>
<td>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.</td>
</tr>
<tr>
<td><b>Revert</b></td>
<td>revert</td>
<td>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.</td>
</tr>
<tr>
<td><b>Security</b></td>
<td>security</td>
<td>The commit improves the security of the product or resolves a security issue that has been reported.</td>
</tr>
</table>

---------

## 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](https://www.npmjs.com/package/git-commit-msg-linter).

### How to Install
```sh
$npm install git-commit-msg-linter --save-dev
```

#### Below you will find a short explanation of how to write these commit messages:

![Commit messages explanation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3xw684bkgajp137ead3j.png)

> We will use the scope to specify the Jira Ticket number in our commit message.

###Comments on git commit -m
<table>
<tr>
<th>Comments</th>
<th>Wrong/Good</th>
</tr>
<tr>
<td>docs: Documentation updates</td>
<td><img alt='wrong comment' height="20" src='https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s9bn60n0nq57g619vepj.png'/></td>
</tr>
<tr>
<td>docs(TK-XXX): add documentation for new API endpoints to improve developer experience</td>
<td><img alt='good comment' height="20" src='https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xes9vpn3wlunn41n2nv3.png'/></td>
</tr>
<tr>
<td>feat: New feature added</td>
<td><img alt='wrong comment' height="20" src='https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s9bn60n0nq57g619vepj.png'/></td>
</tr>
<tr>
<td>feat(TK-XXX): Implement OAuth2 authentication for user login to enhance security and improve user experience</td>
<td><img alt='good comment' height="20" src='https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xes9vpn3wlunn41n2nv3.png'/></td>
</tr>
<tr>
<td>fix: Bug fixes</td>
<td><img alt='wrong comment' height="20" src='https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s9bn60n0nq57g619vepj.png'/></td>
</tr>
<tr>
<td>fix(TK-XXX): Fixed issue with form validation for registration process to prevent invalid user registrations</td>
<td><img alt='good comment' height="20" src='https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xes9vpn3wlunn41n2nv3.png'/></td>
</tr>
<tr>
<td>style: UI updates</td>
<td><img alt='wrong comment' height="20" src='https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s9bn60n0nq57g619vepj.png'/></td>
</tr>
<tr>
<td>style(TK-XXX): Updated CSS for consistent styling across the website and improve usability</td>
<td><img alt='good comment' height="20" src='https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xes9vpn3wlunn41n2nv3.png'/></td>
</tr>
<tr>
<td>chore: Maintenance updates</td>
<td><img alt='wrong comment' height="20" src='https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s9bn60n0nq57g619vepj.png'/></td>
</tr>
<tr>
<td>chore(TK-XXX): Updated deployment process for better scalability and maintainability of the application</td>
<td><img alt='good comment' height="20" src='https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xes9vpn3wlunn41n2nv3.png'/></td>
</tr>
</table>

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!