DEV Community

Higor Anjos
Higor Anjos

Posted on

2 1 1 1 1

Understanding Semantic Versioning

Semantic Versioning (or SemVer) is a standard set of rules used to track software versions during development. This standard provides a clear and consistent way to communicate changes made to a project, allowing developers and users to easily understand the impact of each update.

If you've ever installed packages, frameworks, or software, you've likely seen numbers like 1.2.3 or 2.0.0. These sequences make it easier to understand the type of update made—whether it's a new feature, a bug fix, or a critical change.


Semantic Versioning Format

SemVer follows the format:

MAJOR.MINOR.PATCH
Enter fullscreen mode Exit fullscreen mode

MAJOR Version

The first number represents significant changes to the software that break backward compatibility. This could include removing or altering features, requiring users to adapt.

  • Example: Updating from 1.4.2 to 2.0.0 indicates major and potentially incompatible changes.

MINOR Version

The second number is updated when new features or improvements are added without breaking compatibility with previous versions.

  • Example: Updating from 1.4.2 to 1.5.0 shows that new features were added without affecting existing code.

PATCH Version

The third number is used to indicate bug fixes or minor adjustments that don't alter the software's behavior or features.

  • Example: Updating from 1.4.2 to 1.4.3 reflects a bug fix without structural changes.

Software Release Lifecycle

Alpha

The Alpha version is the first functional version of the software, used internally by developers for initial testing and concept validation. It is unstable and generally unavailable to the public.

Beta

The Beta version is more complete and available for testing by a larger audience to identify bugs and gather feedback. Although functional, it may still contain instabilities.

Release Candidate (RC)

The Release Candidate version is considered stable and close to the final release. If no critical issues are found, it becomes the official software version.


Practical Example

Bug Fix:

  • Current version: 1.0.0
  • New version: 1.0.1 (PATCH)

Example: A bug in an endpoint was fixed without affecting compatibility.

New Feature:

  • Current version: 1.0.1
  • New version: 1.1.0 (MINOR)

Example: A new endpoint was added to manage user permissions.

Breaking Change:

  • Current version: 1.1.0
  • New version: 2.0.0 (MAJOR)

Example: The authentication model was completely refactored, requiring adjustments in systems that consume the API.


Implementing SemVer with GitHub Releases

Create a Tag

To mark a specific version in the repository:

git tag -a v1.0.0 -m "First stable version"
git push origin v1.0.0
Enter fullscreen mode Exit fullscreen mode

Create a Pre-Release

To create a testing version before the official release:

git tag -a v1.1.0-beta -m "Beta version for testing"
git push origin v1.1.0-beta
Enter fullscreen mode Exit fullscreen mode

View Version History

To list all tagged versions:

git tag
Enter fullscreen mode Exit fullscreen mode

Essential Tips and Rules

  • Use the MAJOR.MINOR.PATCH format consistently.
  • Never modify a version that has already been released.
  • Identify pre-release versions with suffixes like -alpha, -beta, or -rc.
  • Document changes using a file like CHANGELOG.md.

    • A standard CHANGELOG.md format:
    # Changelog
    
    ## [1.1.0] - 2025-01-20  
    ### Added  
    - New section on CI/CD tool integration.  
    - More detailed examples using GitHub Actions.  
    
    ## [1.0.0] - 2025-01-18  
    ### Release  
    - Initial content on Semantic Versioning.  
    

With Semantic Versioning, you can communicate changes clearly and effectively, making the development process more organized and predictable.


Version: 1.1.0

Do your career a big favor. Join DEV. (The website you're on right now)

It takes one minute, it's free, and is worth it for your career.

Get started

Community matters

Top comments (0)

Heroku

This site is powered by Heroku

Heroku was created by developers, for developers. Get started today and find out why Heroku has been the platform of choice for brands like DEV for over a decade.

Sign Up

👋 Kindness is contagious

Explore a sea of insights with this enlightening post, highly esteemed within the nurturing DEV Community. Coders of all stripes are invited to participate and contribute to our shared knowledge.

Expressing gratitude with a simple "thank you" can make a big impact. Leave your thanks in the comments!

On DEV, exchanging ideas smooths our way and strengthens our community bonds. Found this useful? A quick note of thanks to the author can mean a lot.

Okay