Merge pull request #51 from reecetech/update-README

Document release workflow and refresh action examples

.github/workflows/test-and-release.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Run ShellCheck
         uses: ludeeus/action-shellcheck@2.0.0
@@ -24,12 +24,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Setup bats
-        uses: mig4/setup-bats@af9a00deb21b5d795cabfeaa8d9060410377686d  # v1.2.0
+        uses: bats-core/bats-action@4.0.0
         with:
-          bats-version: 1.8.0
+          bats-version: 1.14.0
 
       - name: Test
         run: bats tests/*.bats
@@ -40,7 +40,7 @@ jobs:
       github_token: ${{ github.token }}
     steps:
       - name: Checkout code  # have to checkout to have the source code available
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Remove .git directory  # remove the git directory to make the testing valid
         run: rm -rf .git/
@@ -67,6 +67,18 @@ jobs:
         shell: bash
         run: '[[ "$(date +%Y.%-m)" == "$(echo "${{ steps.version-increment.outputs.VERSION }}" | cut -d "." -f 1-2)" ]]'
 
+      - name: Test conventional commit increment version (with API)
+        id: version-increment-conventional
+        run: ./version-increment.sh
+        env:
+          current_version: 1.2.3
+          scheme: conventional_commits
+          use_api: 'true'
+
+      - name: Check conventional commit increment result
+        shell: bash
+        run: '[[ -n "${{ steps.version-increment-conventional.outputs.VERSION }}" ]]'
+
   test-action-yml:  # integration testing
     needs:
       - lint
@@ -78,11 +90,11 @@ jobs:
           - macos-latest
           - ubuntu-latest
           - windows-latest
-      fail-fast: true
+      fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout code  # have to checkout to have the source code available
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Remove .git directory  # remove the git directory to make the testing valid
         shell: bash
@@ -96,7 +108,7 @@ jobs:
           use_api: true
 
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Get next version via Git
         uses: ./
@@ -114,29 +126,44 @@ jobs:
           [[ "${{ steps.version-via-api.outputs.patch-version }}" == "${{ steps.version-via-git.outputs.patch-version }}" ]]
           # Don't test the full version or pre-version, since the number of digits is likely to be different (9 via api vs. 7 via git)
 
+      - name: Get next version via Git with tag-prefix
+        uses: ./
+        id: version-prefix
+        with:
+          scheme: 'semver'
+          use_api: false
+          tag_prefix: 'foo/bar@'
+
+      - name: Check that it starts from 0.0.1 (since prefix doesn't exist)
+        shell: bash
+        run: |
+          [[ "${{ steps.version-prefix.outputs.current-version }}" == "0.0.0" ]]
+          [[ "${{ steps.version-prefix.outputs.major-version }}" == "0" ]]
+          [[ "${{ steps.version-prefix.outputs.minor-version }}" == "0" ]]
+          [[ "${{ steps.version-prefix.outputs.patch-version }}" == "1" ]]
+          [[ "${{ steps.version-prefix.outputs.prefixed-version }}" = "foo/bar@0.0.1"* ]]
+
   release:
+    permissions:
+      contents: write
     needs:
       - test-action-yml
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
-      - name: Lookup version
+      - name: Get next version
-        id: version-lookup
+        uses: ./
-        run: ./version-lookup.sh
+        id: version
-
+        with:
-      - name: Increment version
+          scheme: 'calver'
-        id: version-increment
-        run: ./version-increment.sh
-        env:
-          current_version: ${{ steps.version-lookup.outputs.CURRENT_VERSION }}
-          scheme: calver
 
       - name: Release version
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v3
         if: ${{ github.ref_name == github.event.repository.default_branch }}
         with:
           draft: false
           prerelease: false
-          tag_name: "${{ steps.version-increment.outputs.VERSION }}"
+          tag_name: "${{ steps.version.outputs.version }}"
+          generate_release_notes: true

README.md

@@ -1,5 +1,11 @@
 # Version Increment ➕
 
+This action calculates the next version based on existing Git tags.
+
+Intentionally, this action does not create tags.  It's suggested to use an
+action dedicated to creating tags in a step following the successful steps
+that make up your test, build and releasing process.  See the example below.
+
 ## Use 📄
 
 > [!NOTE]
@@ -9,22 +15,42 @@
 ### Example ⌨️
 
 ```yaml
+name: Build and release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-release:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Get next version
-        uses: reecetech/version-increment@2024.4.3
+        uses: reecetech/version-increment@2026.8.4
         id: version
         with:
           scheme: semver
           increment: patch
 
+      # Example building, using the `version` output from `version-increment`
       - name: Build image
-        uses: docker/build-push-action@v2
+        uses: docker/build-push-action@v7
         with:
-          push: false
           tags: "example/application:${{ steps.version.outputs.version }}"
-          context: .
+
+      - name: Create tag & GitHub release
+        uses: softprops/action-gh-release@v3
+        with:
+          draft: false
+          generate_release_notes: true
+          prerelease: false
+          tag_name: ${{ steps.version.outputs.version }}
 ```
 
 #### API mode 🔗
@@ -34,7 +60,7 @@ use the API mode:
 
 ```yaml
       - name: Get next version
-        uses: reecetech/version-increment@2024.4.3
+        uses: reecetech/version-increment@2026.8.4
         id: version
         with:
           use_api: true
@@ -106,7 +132,7 @@ release branch name as an input.  For example:
 
 ```yaml
       - name: Get next version
-        uses: reecetech/version-increment@2023.10.1
+        uses: reecetech/version-increment@2026.8.4
         id: version
         with:
           release_branch: publish
@@ -132,22 +158,25 @@ Examples:
 | increment      | The digit to increment, either `major`, `minor` or `patch`, ignored if `scheme` == `calver` | No       | `patch`  |
 | release_branch | Specify a non-default branch to use for the release tag (the one without -pre)              | No       |          |
 | use_api        | Use the GitHub API to discover current tags, which avoids the need for a git checkout, but requires `curl` and `jq` | No       | `false`  |
+| tag_prefix     | Prefix the tag with a string (defaults to empty string).  e.g. if set to `@org/product/` the action will filter by this prefix and return `@org/product/1.2.3` in `prefixed-version` output | No       |          |
 
 ### Outputs 📤
 
-| name              | description                                                                                       |
+| name               | description                                                                                                    |
-| :---              | :---                                                                                              |
+| :---               | :---                                                                                                           |
-| current-version   | The current latest version detected from the git repositories tags                                |
+| current-version    | The current latest version detected from the git repositories tags                                             |
-| current-v-version | The current latest version detected from the git repositories tags, prefixed with a `v` character |
+| current-v-version  | The current latest version detected from the git repositories tags, prefixed with a `v` character              |
-| version           | The incremented version number (e.g. the next version)                                            |
+| version            | The incremented version number (e.g. the next version)                                                         |
-| v-version         | The incremented version number (e.g. the next version), prefixed with a `v` character             |
+| v-version          | The incremented version number (e.g. the next version), prefixed with a `v` character                          |
-| major-version     | Major number of the incremented version                                                           |
+| major-version      | Major number of the incremented version                                                                        |
-| minor-version     | Minor number of the incremented version                                                           |
+| minor-version      | Minor number of the incremented version                                                                        |
-| patch-version     | Patch number of the incremented version                                                           |
+| patch-version      | Patch number of the incremented version                                                                        |
-| pre-release-label | Pre-release label of the incremented version                                                      |
+| pre-release-label  | Pre-release label of the incremented version                                                                   |
-| major-v-version   | Major number of the incremented version, prefixed with a `v` character                            |
+| major-v-version    | Major number of the incremented version, prefixed with a `v` character                                         |
-| minor-v-version   | Minor number of the incremented version, prefixed with a `v` character                            |
+| minor-v-version    | Minor number of the incremented version, prefixed with a `v` character                                         |
-| patch-v-version   | Patch number of the incremented version, prefixed with a `v` character                            |
+| patch-v-version    | Patch number of the incremented version, prefixed with a `v` character                                         |
+| prefixed-version   | Incremented version calculated, including a `tag_prefix` if specified                                          |
+| prefixed-v-version | Incremented version calculated, prefixed with a `v` charatcter, and also including a `tag_prefix` if specified |
 
 ## Contributing 💕
 

action.yml

@@ -40,6 +40,11 @@ inputs:
     description: 'Use the GitHub API to discover current tags, which avoids the need for a git checkout, but requires `curl` and `jq`'
     required: false
     default: false
+  tag_prefix:
+    description: |
+      Prefix the tag with a string (defaults to empty string).  e.g. if set to `@org/product/` the action will filter by this prefix and return `@org/product/1.2.3` in `prefixed-version` output
+    required: false
+    default: ''
 
 outputs:
   current-version:
@@ -75,6 +80,12 @@ outputs:
   patch-v-version:
     description: 'Patch number of the incremented version, prefixed with a `v` charatcter'
     value: ${{ steps.version-increment.outputs.PATCH_V_VERSION }}
+  prefixed-version:
+    description: 'Incremented version calculated, including a `tag_prefix` if specified'
+    value: ${{ inputs.tag_prefix}}${{ steps.version-increment.outputs.VERSION }}
+  prefixed-v-version:
+    description: 'Incremented version calculated, prefixed with a `v` charatcter, and also including a `tag_prefix` if specified'
+    value: ${{ inputs.tag_prefix}}${{ steps.version-increment.outputs.V_VERSION }}
 
 runs:
   using: "composite"
@@ -86,6 +97,7 @@ runs:
         github_token: ${{ github.token }}
         scheme: ${{ inputs.scheme }}
         use_api: ${{ inputs.use_api }}
+        tag_prefix: ${{ inputs.tag_prefix }}
 
     - id: version-increment
       run: "${GITHUB_ACTION_PATH}/version-increment.sh"

shared.sh

@@ -14,6 +14,22 @@ pcre_master_ver='^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9
 pcre_allow_vprefix="^v{0,1}${pcre_master_ver:1}"
 pcre_old_calver='^(?P<major>0|[1-9]\d*)-0{0,1}(?P<minor>0|[0-9]\d*)-R(?P<patch>0|[1-9]\d*)$'
 
+##==----------------------------------------------------------------------------
+##  Utility function for removing tag_prefix if present
+
+remove_prefix() {
+    local tag="$1"
+    if [[ -n "${tag_prefix:-}" ]]; then
+        if [[ "${tag}" == "${tag_prefix}"* ]]; then
+            printf '%s\n' "${tag:${#tag_prefix}}"
+        else
+            printf '\n'
+        fi
+    else
+        printf '%s\n' "${tag}"
+    fi
+}
+
 ##==----------------------------------------------------------------------------
 ## Conventional commit regexes
 ## see: https://www.conventionalcommits.org/en/v1.0.0/
@@ -51,6 +67,9 @@ if [[ "${use_api}" == 'true' ]] ; then
     fi
 fi
 
+# Check if the tag_prefix is set, and if not, set it to an empty string
+tag_prefix="${tag_prefix:-}"
+
 ##==----------------------------------------------------------------------------
 ##  MacOS compatibility
 

tests/test_version-increment.bats

@@ -282,6 +282,34 @@ function init_repo {
     [[ "$output" = *"VERSION=$(date +%Y.%-m.1)+pre.${short_ref}"* ]]
 }
 
+@test "uses the API commit message for conventional commits without a checkout" {
+    local no_checkout_dir="${BATS_TEST_TMPDIR}/no-checkout"
+    local mock_bin="${BATS_TEST_TMPDIR}/bin"
+
+    mkdir -p "${no_checkout_dir}" "${mock_bin}"
+    printf '%s\n' \
+        '#!/usr/bin/env bash' \
+        'printf "%s\n" "{\"commit\":{\"message\":\"feat: API-only change\"}}"' \
+        > "${mock_bin}/curl"
+    chmod +x "${mock_bin}/curl"
+
+    export PATH="${mock_bin}:${PATH}"
+    export current_version=1.2.3
+    export scheme="conventional_commits"
+    export use_api="true"
+    export github_token="test-token"
+    export GITHUB_REF="refs/heads/main"
+    export GITHUB_SHA="abcdef1234567890"
+    export GITHUB_API_URL="https://fake.github.example.com"
+    export GITHUB_REPOSITORY="gh-org/example"
+
+    run bash -c 'cd "$1" && version-increment.sh' -- "${no_checkout_dir}"
+
+    print_run_info
+    [ "$status" -eq 0 ] &&
+    [[ "$output" = *"VERSION=1.3.0"* ]]
+}
+
 @test "increments the patch version after a fix commit (conventional commits)" {
     init_repo
 
@@ -409,3 +437,24 @@ function init_repo {
     [[ "$output" = *"VERSION=1.2.4"* ]]
     [[ "$output" = *"No conventional commit found"* ]]
 }
+
+
+@test "increments the patch version by default if no conventional commits found and enabled (conventional commits) (with tag_prefix)" {
+    init_repo
+
+    export tag_prefix="@org/product@"
+    export current_version="1.2.3"
+    export scheme="conventional_commits"
+
+    echo "some new change" > feat.txt
+    git add feat.txt
+    git commit -m "new change"
+
+    run ../../version-increment.sh
+
+    print_run_info
+    [ "$status" -eq 0 ] &&
+    [[ "$output" = *"VERSION=1.2.4"* ]]
+    [[ "$output" = *"V_VERSION=v1.2.4"* ]]
+    [[ "$output" = *"No conventional commit found"* ]]
+}

tests/test_version-lookup.bats

@@ -72,6 +72,66 @@ function init_repo {
     [[ "$output" = *"CURRENT_V_VERSION=v0.1.2"* ]]
 }
 
+@test "finds the current normal version with tag_prefix enabled" {
+    init_repo
+
+    export tag_prefix="@org/product@"
+
+    git tag @org/product@0.0.1
+    git tag @org/product@0.1.1
+    git tag @org/product@0.1.2
+
+    run version-lookup.sh
+
+    print_run_info
+    [ "$status" -eq 0 ] &&
+    [[ "$output" = *"CURRENT_VERSION=0.1.2"* ]]
+}
+
+@test "tag_prefix enabled prefixes with a v" {
+    init_repo
+
+    export tag_prefix="@org/product/"
+
+    git tag @org/product/0.1.2
+
+    run version-lookup.sh
+
+    print_run_info
+    [ "$status" -eq 0 ] &&
+    [[ "$output" = *"CURRENT_VERSION=0.1.2"* ]] &&
+    [[ "$output" = *"CURRENT_V_VERSION=v0.1.2"* ]]
+}
+
+@test "treats tag_prefix as a literal string" {
+    init_repo
+
+    export tag_prefix="v."
+
+    git tag v.1.2.3
+    git tag v1.9.9
+
+    run version-lookup.sh
+
+    print_run_info
+    [ "$status" -eq 0 ] &&
+    [[ "$output" = *"CURRENT_VERSION=1.2.3"* ]]
+}
+
+@test "supports a tag_prefix containing a sed delimiter" {
+    init_repo
+
+    export tag_prefix="foo|bar@"
+
+    git tag "foo|bar@1.2.3"
+
+    run version-lookup.sh
+
+    print_run_info
+    [ "$status" -eq 0 ] &&
+    [[ "$output" = *"CURRENT_VERSION=1.2.3"* ]]
+}
+
 @test "finds the current normal version even if there's a newer pre-release version" {
     init_repo
 
@@ -85,6 +145,24 @@ function init_repo {
     [[ "$output" = *"CURRENT_VERSION=1.2.300"* ]]
 }
 
+@test "finds only prefixed tags when tag_prefix set" {
+    init_repo
+
+    export tag_prefix="my_product-"
+
+    git tag my_product-0.1.2
+    git tag my_product-0.1.3-dev.123
+    git tag 2.4.5
+    git tag 2.4.6-dev.456
+
+    run version-lookup.sh
+
+    print_run_info
+    [ "$status" -eq 0 ] &&
+    [[ "$output" = *"CURRENT_VERSION=0.1.2"* ]] &&
+    [[ "$output" = *"CURRENT_V_VERSION=v0.1.2"* ]]
+}
+
 @test "returns 0.0.0 if no normal version detected" {
     init_repo
 
@@ -107,6 +185,20 @@ function init_repo {
     [[ "$output" = *"CURRENT_VERSION=0.0.0"* ]]
 }
 
+@test "returns 0.0.0 if no prefix version detected even if there's a non-prefix release version" {
+    init_repo
+
+    export tag_prefix="code/"
+
+    git tag 0.1.0
+
+    run version-lookup.sh
+
+    print_run_info
+    [ "$status" -eq 0 ] &&
+    [[ "$output" = *"CURRENT_VERSION=0.0.0"* ]]
+}
+
 @test "returns a calver if no normal version detected and calver scheme specified" {
     init_repo
 

version-increment.sh

@@ -63,7 +63,18 @@ fi
 ##  Conventional commits
 if [[ "${scheme}" == 'conventional_commits' ]] ; then
     # Get message from given commit
-    commit_message=$(git log -1 --pretty=format:%B "${git_commit_sha}")
+    if [[ "${use_api:-}" == 'true' ]] ; then
+        commit_message="$(
+            curl -fsSL \
+                -H "Accept: application/vnd.github+json" \
+                -H "Authorization: Bearer ${github_token}" \
+                -H "X-GitHub-Api-Version: 2022-11-28" \
+                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/commits/${git_commit_sha}" \
+            | jq -r '.commit.message'
+        )"
+    else
+        commit_message="$(git log -1 --pretty=format:%B "${git_commit_sha}")"
+    fi
 
     # Check commit message header
     found_match='false'

version-lookup.sh

@@ -32,12 +32,18 @@ if [[ "${use_api:-}" == 'true' ]] ; then
             -H "X-GitHub-Api-Version: 2022-11-28" \
             "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/git/matching-refs/tags/" \
         | jq -r '.[].ref' | sed 's|refs/tags/||g' \
-        | { grep_p "${pcre_allow_vprefix}" || true; } | sed 's/^v//g' | sort -V | tail -n 1
+        | while read -r tag; do remove_prefix "$tag"; done \
+        | { grep_p "${pcre_allow_vprefix}" || true; } \
+        | sed 's/^v//g' \
+        | sort -V | tail -n 1
     )"
 else
     current_version="$(
         git tag -l \
-        | { grep_p "${pcre_allow_vprefix}" || true; } | sed 's/^v//g' | sort -V | tail -n 1
+        | while read -r tag; do remove_prefix "$tag"; done \
+        | { grep_p "${pcre_allow_vprefix}" || true; } \
+        | sed 's/^v//g' \
+        | sort -V | tail -n 1
     )"
 fi