Semantic Versioning and Conventional Commits

Table of contents

• What is Versioning? 
• The Semantic Versioning
• Variants in Semantic Versioning
• The possibility of having a 0.0.0 version
• Conventional Commits
• Benefits for security and development
• Are there alternatives to Conventional Commits?
• Comparison with Conventional Commits

This article explores two fundamental tools for organizing development team workflows: Semantic Versioning (SemVer), a methodology for semantic versioning of code, and Conventional Commits, a convention for standardizing commit messages. 

Both improve clarity, efficiency, and security in software release and maintenance processes. 

What is Versioning? 

Versioning is the process of assigning a unique and progressive identifier to each new version of a software product. This helps catalog changes, track bug fixes, and release structured updates. 

Version control tools like Git are essential for tracking changes and allowing developers to work on multiple branches simultaneously. 

Advantages of Versioning: 

• Improves the tracking of changes made;
• Facilitates tracking of problems reported by users, helping the product maintainer to better identify the problem.
• Allows the same product to be used with different functionality depending on the needs and availability of the end user (tester, developer, or common user);
• Allows clear communication of new functionality: allows the user to identify the functionality used in the product by reading the associated release documentation.
• Support for open source environments, where multiple developers collaborate on the same project;
• Enables parallelization of work, since it is possible to work with multiple versions at the same time for the same product, speeding up the deployment process. In essence, it ensures the ability to manage patch versions, minor versions and major versions in parallel, each tailored to specific needs.

The Semantic Versioning

What is SemVer? Semantic versioning is a standard that defines a structured format for version numbers: MAJOR.MINOR.PATCH. This method helps developers and users easily understand the nature of changes introduced in each version. 

• MAJOR
  Incremented when changes break backward compatibility. 

• MINOR
  Updated when adding new features while maintaining compatibility. 

• PATCH
  Incremented for bug fixes that do not affect compatibility. 

For example the version 1.0.0:

• You upgrade to 1.0.1 not only in case of vulnerabilities but also in case of bug fixes;
• A minor release version introducing features leads to 1.1.0;
• Incompatible changes with earlier versions generate 2.0.0.

This structured approach makes Semantic Versioning a widely recognized standard, easily integrated into CI/CD processes. 

Another example of semantics version

1.3.5 (1 = major, 3 = minor, 5 = patch)

Hierarchical updates:

• Compatible fixes: 1.3.5 → 1.3.6 

• New compatible features: 1.3.5 → 1.4.0 

• Breaking changes: 1.3.5 → 2.0.0 

Variants in Semantic Versioning

In addition to the basic structure of semantics versioning, there are useful extensions for the development and testing phase:

• Pre-release identifiers
  Like -alpha or -beta, they signal unstable versions.
• Build metadata
  Like +20240101, they add build information without affecting the version number.

Example
1.0.0-alpha indicates an experimental phase, while 1.0.0+build1234 may include specific details.

The possibility of having a 0.0.0 version

It is not possible to have a version 0.0.0 according to SemVer guidelines. This is because the value 0 for MAJOR represents a stage where the product is still in development and is not considered ready for an official release.

In practice, the lowest version allowed is 0.1.0. Here’s how it works:

• The value 0 in the MAJOR
  Indicates that the product is in an early, pre-release phase, during which it may undergo substantial and frequent changes, with the possibility of introducing changes that break compatibility without special constraints.
• The MINOR and PATCH values
  Are used to identify progressive updates during this phase of development.
• MINOR
  Is incremented to add new features that do not break internal code compatibility.
• PATCH
  Is incremented to fix bugs or make minor changes.

When to upgrade to 1.0.0

Once the product reaches sufficient stability to be distributed to the public or used in production environments, the MAJOR is incremented to 1, and it is changed to version 1.0.0.

This version change signals that the product is ready for wider use and that any changes that break compatibility will be treated with greater caution, following SemVer rules.

Practical example

Suppose we have an early stage project:

• first development version: 0.1.0;
• addition of a new feature during development: 0.2.0;
• bug fix: 0.2.1.

Once development is completed and some stability has been achieved, it will be changed to version 1.0.0 to indicate the first official release.

In summary, the numbering 0.0.0 is not contemplated because it would not make practical sense: the 0 in the MAJOR already represents a preliminary stage, while the MINOR and PATCH values serve to define specific progress at that stage.

Conventional Commits

If SemVer simplifies version management, Conventional Commits ensure consistency in the documentation of code changes. This standardizes commit messages in the format:

<type>([optional scope]): <description> 

[optional body] 

[optional footer(s)]

 Each commit includes:

• Type
  Specifies the Macro-activity, nature of the change (feat, fix, chore, etc.).
• Scope (optional).
  Specifies the section of the code affected.
• Description
  Brief explanation of the change.
• Body (optional)
  Additional details.
• Footer (optional)
  Metadata such as ticket or reviewer references.

Example

fix(command): modified overwrite request. 

Overwrite now deletes the last file instead of creating a new one 

Reviewed by: PB 

Refs: a00078c

Conventional Commits can be linked to SemVer:

• A commit fix increments the patch version (e.g., 1.3.5 → 1.3.6);
• A commit feat increments the minor version (e.g., 1.3.5 → 1.4.0);
• A commit with BREAKING CHANGE increments the major version (e.g., 1.3.5 → 2.0.0).

Benefits for security and development

The adoption of SemVer and Conventional Commits offers concrete advantages, especially in open source projects:

• Improves readability of change history;
• Automates the generation of changelogs;
• Supports CI/CD pipelines for more secure release;
• Allows users to choose versions according to their needs.

Are there alternatives to Conventional Commits?

Yes, there are several alternatives to Conventional Commits, which may be equally viable depending on the needs of the project and the tools used. Although Conventional Commits are a solid and widely adopted proposition, other conventions or tools may offer similar or complementary functionality.

Here are some useful alternatives and approaches:

Gitmoji

The Gitmoji format is an informal and visually appealing alternative that uses emoji to identify the type of change made. For example:

• Fix
  Bug fix.
• Feat
  Addition of a new feature.
• Docs
  Changes to the documentation.
• Perf
  Performance improvement.

This convention makes commit history more immediate and easy to read, especially for teams that prefer a lighter, less formal approach.

Gitflow Workflow

Gitflow Workflow is a branch management model (branches) that establishes a hierarchical structure for code development. While it is not a convention on commit messages, Gitflow allows for better organization of the development cycle and release of versions.

The main branches are:

• Main/master
  Contains production-ready code.
• Develop
  Contains code under development.
• Feature/
  Branches dedicated to new features.
• Hotfix/
  Branches to fix urgent bugs.
• Release/
  Branches to finalize a new version.

Although Gitflow does not define how to write commits, the branch structure can be supplemented with other conventions, such as Conventional Commits, to improve consistency.

Custom Commit message guidelines

Some teams prefer to create custom commit message guidelines. These rules are often tailored to the specific context of the project and may include:

• Rreferences to ticket numbers (e.g., Jira, Trello);
• Priority levels for the type of change;
• Special stylistic rules to make commits readable and understandable.

Example
A commit could be written as follows: 

[TASK-123] Added support for multi-language feature.

Changelog-first approach

This methodology places the changelog at the center of code management. Instead of focusing on commit messages, developers write a clear changelog update first and then associate it with commits.

Tools such as Keep a Changelog or CI/CD plugins can automate the association between changelog and commit messages.

Instruments and integrations with Issue Tracker

Many project management tools, such as Jira, Wrike or ClickUp, offer integrations with version control systems (VCS) to keep code in order.

Example
A commit could directly include a reference to a specific task. And commit conventions can be based on the format required by the tool (e.g., TASK-101: Update database schema).

These tools can also automate the link between code and task manager, simplifying change tracking.

Squash Commits 

In some projects, instead of defining a convention for each commit, we prefer to use squash commits, that is, consolidating multiple commits into one at merge time.

This approach is particularly useful for maintaining a clean commit history, especially in public repositories with many contributors.

Example
A series of commits with descriptive but non-standard messages is compressed into a single structured commit at the time of merge into the main branch.

Comparison with Conventional Commits

Each alternative has advantages and disadvantages compared to Conventional Commits. Here are some aspects to consider:

• Formalities
  Conventional Commits are more rigorous than Gitmoji or custom guidelines.
• Automation
  Many alternatives do not support automatic changelog generation or CI/CD pipeline activation as Conventional Commits do.
• Adaptability
  Custom or tool-based solutions such as Jira may be more flexible but less standardized.
• Accessibility
  Visual approaches such as Gitmoji are intuitive for less technical teams, while Conventional Commits are geared toward projects with more complex requirements.

Conclusion 

In today’s complex technological landscape, Semantic Versioning and Conventional Commits are essential for clear, structured, and secure development workflows. 

By managing version numbers and commit messages systematically, both technical and non-technical stakeholders benefit from improved clarity, automation, and efficiency. 

Questions and answers

1. What is Semantic Versioning?
   It is a semantic versioning system that assigns version numbers based on MAJOR, MINOR and PATCH changes.
2. What is the basic structure of a version number?
   MAJOR.MINOR.PATCH, where each segment is separated by dots and represents a category of changes.
3. What does a minor release indicate?
   A minor release introduces new features without breaking backward compatibility.
4. What is the significance of version 1.0.0?
   Version 1.0.0 represents the first stable release of a product.
5. When is the patch version incremented?
   For every bug fix compatible with previous versions.
6. What is the difference between major and minor versions?
   A major version introduces incompatible changes; a minor version adds new compatible features.
7. How do pre-release identifiers work?
   They identify unstable versions, such as -alpha or -beta, used during development.
8. Why use Conventional Commits?
   They standardize commit messages, improving readability and automation of CI/CD processes.
9. Can Semantic Versioning be used in open source projects?
   Yes, it is ideal for organizing new versions in collaborative projects.
10. How to automate versioning with Semantic Versioning?
    Through integration with CI/CD tools, which automatically generate version numbers and changelogs.
11. How to make sure that all contributors use Conventional Commits?
    It is sufficient to request a pull request to review and consolidate commits.
12. What to do if I find a problem after release?
    If the problem emerges in testing, you can add a pre-release; otherwise, increment the PATCH.