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

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

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

View Version History

To list all tagged versions:

git tag

---

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}