semver.sh

This Bash script automates semantic versioning for Git branches following the GitFlow branching model, supporting a flexible tag strategy. It's designed for CI pipelines, ensuring consistent versioning across development, release, and hotfix branches. It also adapts to project-specific workflows, making it ideal for multi-project environments.

Key Features

Branch-Based Versioning:

• Develop Branch: Version with pre-release type set to dev.
• Release Branches: Version with pre-release type set to rc or stable release types ga and rc, where the patch version is always set to zero.
• Hotfix Branches: Version with pre-release type set to rc or stable release types ga and rc, where the patch version is automatically calculated.
• Pull Request: Version where the pre-release type is set to pr, and the version increment is based on the PR number.

Version Increment Source Selection:

• Commit Count: Increments based on the number of commits since the last marker tag.
• PR Number: Increment based on the pull request number (useful for PR-based versioning).

Breaking Change Detection:

• Automatically increments the major version when breaking changes are detected using commit messages:
  • ! symbol in the commit title (following Conventional Commit standards).
  • BREAKING CHANGE section in the commit body.
• Optionally excludes breaking changes from specific authors (e.g., dependabot[bot]).

Project-Specific Workflows:

• Supports multiple GitFlow instances within a single repository.
• Allows independent versioning and release management for different projects or sub-projects using */-prefixed branches (e.g., project-a/develop, project-a/release/v1.0.0).

Usage

Syntax

Usage: semver.sh [COMMAND] [OPTIONS]

Commands:
  show-version                 Display the semantic version for the specified
                               branch or the current branch if none is
                               provided.
  create-release-branch        Create a new release branch using the calculated
                               semantic version.
  create-hotfix-branch         Create a new hotfix branch for patching a stable
                               version.
  finish-release-branch        Finalize a release branch by tagging and marking
                               it as stable.
  finish-hotfix-branch         Finalize a hotfix branch by tagging and marking
                               it as stable.

Options:
  General Options:
    --project-name <name>      Project name to prefix branches and tags.
                               Defaults to an empty string.
    --base-version <version>   Base version to use if no tags are found.
                               Defaults to "0.1.0".
    --json                     Output information in JSON format.
    -q, --quiet                Suppress detailed output showing the branches
                               and tags being created.
    -h, --help                 Display this help message and exit.

  show-version Options:
    (inherits General Options)
    --branch <branch>          Branch to calculate the semantic version for.
                               Defaults to the current branch.
    --increment-source <source>
                               Source for determining version increments:
                                - commit-sequence (default)
                                - pr-number
    --pr-number <number>       Pull request number for version calculation.
                               Required if --increment-source="pr-number".
    --skip-breaking-changes-from <author>
                               Ignore breaking changes from a specific author
                               (e.g., dependabot[bot]).
                               Repeat the option to specify multiple authors.

  create-release-branch Options:
    (inherits General Options)
    --skip-breaking-changes-from <author>
                               Ignore breaking changes from a specific author
                               (e.g., dependabot[bot]).
                               Repeat the option to specify multiple authors.

  create-hotfix-branch Options:
    (inherits General Options)
    --branch <branch>          Specify the branch of the stable version to
                               patch (e.g., release/v1.2.0).

  finish-release-branch Options:
    (inherits General Options)
    --branch <branch>          Specify the release branch to finalize (e.g.,
                               release/v1.2.0).
    --release-type <type>      Type of release for the version:
                                - ga: general availability (default)
                                - la: limited availability

  finish-hotfix-branch Options:
    (inherits General Options)
    --branch <branch>          Specify the hotfix branch to finalize (e.g.,
                               hotfix/1.2.1).
    --release-type <type>      Type of release for the version:
                                - ga: general availability (default)
                                - la: limited availability

Commands:

1. show-version

Calculates and displays the semantic version of a branch.

Options:

• --branch <branch>: Specifies which branch to calculate the version for (default: current branch).
• --increment-source <source>: Determines the version increment source:
  • commit-sequence (default): Increment based on commit count.
  • pr-number: Use the pull request number.
• --pr-number <number>: Required if --increment-source=pr-number.
• --skip-breaking-changes-from <author>: Exclude breaking changes from a specific author (e.g., dependabot[bot]).

2. create-release-branch

Creates a new release branch with a version derived from the current state of the develop branch.

Options:

• Inherits the general options such as --project-name and --base-version.
• --skip-breaking-changes-from <author>: Exclude breaking changes from a specific author.

3. create-hotfix-branch

Creates a hotfix branch to patch an existing release or hotfix branch.

Options:

• Inherits the general options such as --project-name and --base-version.
• --branch <branch>: The stable branch to patch (e.g., release/v1.2.0).

4. finish-release-branch

Finalizes a release branch by tagging it and marking it as stable.

Options:

• Inherits the general options such as --project-name and --base-version.
• --branch <branch>: The release branch to finalize (e.g., release/v1.2.0).
• --release-type <type>: Defines the release type:
  • ga (default): General availability.
  • la: Limited availability.

5. finish-hotfix-branch

Finalizes a hotfix branch by tagging it and marking it as stable.

Options:

• Inherits the general options such as --project-name and --base-version.
• --branch <branch>: The hotfix branch to finalize (e.g., hotfix/1.2.1).
• --release-type <type>: Defines the release type:
  • ga (default): General availability.
  • la: Limited availability.

Examples

1. Calculate version based on commit sequence for develop:

   ./semver.sh show-version --branch "develop" --increment-source "commit-sequence"

2. Calculate version using PR number on a release branch:

   ./semver.sh show-version --branch "release/v1.0.0" --increment-source "pr-number" --pr-number "42"

3. Exclude breaking changes from dependabot[bot]:

   ./semver.sh show-version --branch "develop" --skip-breaking-changes-from "dependabot\[bot\]"

4. Support project-specific workflows:

   ./semver.sh show-version --project-name "project-a" --branch "project-a/release/v7.5.0" --increment-source "commit-sequence"

5. Specify a base version for legacy repositories:

   ./semver.sh show-version --base-version "1.2.3" --branch "develop" --increment-source "commit-sequence"

How It Works

Tag Creation

When a release or hotfix branch is created, a start marker tag is created to mark the beginning of the branch:

• [<project-name>-]v*-release-start-marker: Starting point for develop and release branches.
• [<project-name>-]v*-hotfix-start-marker: Starting point for hotfix branches.

Versioning Rules

1. Develop Branch ([<project-name>/]develop)

   • Pre-release type: dev
   • Increment major for breaking changes, minor otherwise.
   • Format: \<major\>.\<minor\>.0-dev.\<increment\>.

2. Release Branch ([<project-name>/]release/*)

   • Pre-release type: rc, or stable types ga (default), la.
   • Patch version is always 0.
   • Format: \<major\>.\<minor\>.0-rc.\<increment\> (before stable).

3. Hotfix Branch ([<project-name>/]hotfix/*)

   • Pre-release type: rc, or stable types ga (default), la.
   • Patch version is calculated dynamically.
   • Format: \<major\>.\<minor\>.\<patch\>-rc.\<increment\> (before stable).

4. Pull Requests (pr/*)

   • Pre-release type: pr.
   • Version increment is set to the PR number.
   • Format: \<major\>.\<minor\>.\<patch\>-pr.\<pr-number\>.

Requirements

• Bash 4.0+
• Git installed and available in the PATH