sync with diff-common.sh

Author: vmelamed

README.md

@@ -56,7 +56,7 @@ Then run the generated `scripts/bootstrap-new-package.sh` to create and push the
 ### Template parameters (key ones)
 
 | Parameter             | Default    | Description                                                                |
-|:--------------------- |:-------    |:-------------------------------------------------------------------------- |
+| :-------------------- | :--------- | :------------------------------------------------------------------------- |
 | `--name`              | (required) | Package/project name (PascalCase); repo becomes `vm2.<name>`               |
 | `--initialVersion`    | `0.1.0`    | Initial version used in README/CHANGELOG; MinVer computes build versions   |
 | `--license`           | `MIT`      | One of `MIT`, `Apache-2.0`, `BSD-3`; materializes LICENSE and SPDX headers |
@@ -141,7 +141,7 @@ Then run the generated `scripts/bootstrap-new-package.sh` to create and push the
    - `MIN_COVERAGE_PCT`: `80`%: Minimum code coverage percentage required
    - `NUGET_SERVER`: `github`: the NuGet server to publish to (supported values: 'github', 'nuget', or custom URI)
    - `SAVE_PACKAGE_ARTIFACTS`: `false`: Whether to save package artifacts after build/publish
-   - `SEMVER_PRERELEASE_PREFIX`: `preview`: Prefix for the prerelease tag, e.g. 'preview', 'alpha', 'beta', 'rc', etc.
+   - `MINVERDEFAULTPRERELEASEIDENTIFIERS`: `preview`: Prefix for the prerelease tag, e.g. 'preview.0', 'alpha', 'beta', 'rc', etc.
 1. Protect `main` with required checks and require PRs. Suggested check names:
    - `build` (job id from CI workflow "CI: Build, Test, Benchmark")
    - `test` (job id from CI workflow "CI: Build, Test, Benchmark")

templates/AddNewPackage/content/.github/workflows/CI.yaml

@@ -50,6 +50,8 @@ jobs:
       configuration: ${{ vars.CONFIGURATION }}
       min-coverage-pct: ${{ vars.MIN_COVERAGE_PCT }}
       max-regression-pct: ${{ vars.MAX_REGRESSION_PCT }}
+      minver-tag-prefix: ${{ vars.MINVERTAGPREFIX || 'v' }}
+      minver-prerelease-id: ${{ vars.MINVERDEFAULTPRERELEASEIDENTIFIERS || 'preview.0' }}
     outputs:
       build-projects: ${{ steps.init-params.outputs.build-projects }}
       test-projects: ${{ steps.init-params.outputs.test-projects }}
@@ -60,6 +62,8 @@ jobs:
       preprocessor-symbols: ${{ steps.init-params.outputs.preprocessor-symbols }}
       min-coverage-pct: ${{ steps.init-params.outputs.min-coverage-pct }}
       max-regression-pct: ${{ steps.init-params.outputs.max-regression-pct }}
+      minver-tag-prefix: ${{ steps.init-params.outputs.minver-tag-prefix }}
+      minver-prerelease-id: ${{ steps.init-params.outputs.minver-prerelease-id }}
     steps:
       - name: Gather parameters
         id: init-params
@@ -73,6 +77,8 @@ jobs:
           configuration='${{ env.configuration }}'
           min_coverage_pct='${{ env.min-coverage-pct }}'
           max_regression_pct='${{ env.max-regression-pct }}'
+          minver_tag_prefix='${{ env.minver-tag-prefix }}'
+          minver_prerelease_id='${{ env.minver-prerelease-id }}'
 
           if [ '${{ github.event_name }}' == "push" ]; then
               # Set the values for push events, and add SHORT_RUN to preprocessor_symbols for faster benchmark tests (less precise, yet acceptable for CI runs).
@@ -104,6 +110,8 @@ jobs:
               echo "configuration=${configuration}"
               echo "min-coverage-pct=${min_coverage_pct}"
               echo "max-regression-pct=${max_regression_pct}"
+              echo "minver-tag-prefix=${minver_tag_prefix}"
+              echo "minver-prerelease-id=${minver_prerelease_id}"
           }  >> $GITHUB_OUTPUT
 
   call-ci:
@@ -129,3 +137,5 @@ jobs:
       benchmark-projects: ${{ needs.get-params.outputs.benchmark-projects }}
       min-coverage-pct: ${{ fromJSON(needs.get-params.outputs.min-coverage-pct) }}
       max-regression-pct: ${{ fromJSON(needs.get-params.outputs.max-regression-pct) }}
+      minver-tag-prefix: ${{ needs.get-params.outputs.minver-tag-prefix }}
+      minver-prerelease-id: ${{ needs.get-params.outputs.minver-prerelease-id }}

templates/AddNewPackage/content/.github/workflows/Prerelease.yaml

@@ -9,7 +9,7 @@ on:
 
   workflow_dispatch:
     inputs:
-      semver-prerelease-prefix:
+      minver-prerelease-id:
         description: "Prerelease prefix (e.g. preview, alpha, beta, rc1, etc.)"
         type: string
         required: true
@@ -36,34 +36,34 @@ jobs:
       package-projects: ${{ steps.init-params.outputs.package-projects }}
       nuget-server: ${{ steps.init-params.outputs.nuget-server }}
       minver-tag-prefix: ${{ steps.init-params.outputs.minver-tag-prefix }}
-      semver-prerelease-prefix: ${{ steps.init-params.outputs.semver-prerelease-prefix }}
+      minver-prerelease-id: ${{ steps.init-params.outputs.minver-prerelease-id }}
       reason: ${{ steps.init-params.outputs.reason }}
       save-package-artifacts: ${{ steps.init-params.outputs.save-package-artifacts }}
     steps:
       - name: Gather parameters
         id: init-params
         shell: bash
         run: |
-          dotnet_version='${{ vars.DOTNET_VERSION }}'
           package_projects='${{ env.PACKAGE_PROJECTS }}'
           nuget_server='${{ env.NUGET_SERVER }}'
+          dotnet_version='${{ vars.DOTNET_VERSION }}'
           minver_tag_prefix='${{ vars.MINVERTAGPREFIX || 'v' }}'
-          semver_prerelease_prefix='${{ vars.SEMVER_PRERELEASE_PREFIX || 'preview' }}'
-          reason=$(printf "%s %s" "$semver_prerelease_prefix" "pre-release (PR to main)")
+          minver_prerelease_id='${{ vars.MINVERDEFAULTPRERELEASEIDENTIFIERS || 'preview.0' }}'
+          reason="$minver_prerelease_id pre-release (PR to main)"
           save_package_artifacts='${{ vars.SAVE_PACKAGE_ARTIFACTS || 'false' }}'
 
           if [ '${{ github.event_name }}' == "workflow_dispatch" ]; then
-              semver_prerelease_prefix='${{ inputs.semver-prerelease-prefix }}'
+              minver_prerelease_id='${{ inputs.minver-prerelease-id }}'
               reason='${{ inputs.reason }}'
           fi
 
           # Set the outputs:
           {
-              echo "dotnet-version=${dotnet_version}"
               echo "package-projects=${package_projects}"
               echo "nuget-server=${nuget_server}"
+              echo "dotnet-version=${dotnet_version}"
               echo "minver-tag-prefix=${minver_tag_prefix}"
-              echo "semver-prerelease-prefix=${semver_prerelease_prefix}"
+              echo "minver-prerelease-id=${minver_prerelease_id}"
               echo "reason=${reason}"
               echo "save-package-artifacts=${save_package_artifacts}"
           }  >> $GITHUB_OUTPUT
@@ -98,6 +98,6 @@ jobs:
       package-projects: ${{ needs.get-params.outputs.package-projects }}
       nuget-server: ${{ needs.get-params.outputs.nuget-server }}
       minver-tag-prefix: ${{ needs.get-params.outputs.minver-tag-prefix }}
-      semver-prerelease-prefix: ${{ needs.get-params.outputs.semver-prerelease-prefix }}
+      minver-prerelease-id: ${{ needs.get-params.outputs.minver-prerelease-id }}
       reason: ${{ needs.get-params.outputs.reason }}
       save-package-artifacts: ${{ fromJson(needs.get-params.outputs.save-package-artifacts) }}

templates/AddNewPackage/content/.github/workflows/Release.yaml

@@ -26,11 +26,14 @@ jobs:
       ${{
       github.event_name == 'workflow_dispatch' ||
       !contains(github.ref_name,'-') &&
-      startsWith(github.ref, format('refs/tags/%s', vars.MinVerTagPrefix || 'v'))
+      startsWith(github.ref, format('refs/tags/%s', vars.MINVERTAGPREFIX || 'v'))
       }}
     outputs:
+      dotnet-version: ${{ steps.init-params.outputs.dotnet-version }}
       package-projects: ${{ steps.init-params.outputs.package-projects }}
       nuget-server: ${{ steps.init-params.outputs.nuget-server }}
+      minver-tag-prefix: ${{ steps.init-params.outputs.minver-tag-prefix }}
+      reason: ${{ steps.init-params.outputs.reason }}
       save-package-artifacts: ${{ steps.init-params.outputs.save-package-artifacts }}
     steps:
       - name: Gather parameters
@@ -39,12 +42,22 @@ jobs:
         run: |
           package_projects='${{ env.PACKAGE_PROJECTS }}'
           nuget_server='${{ env.NUGET_SERVER }}'
+          dotnet_version='${{ vars.DOTNET_VERSION }}'
+          minver_tag_prefix='${{ vars.MINVERTAGPREFIX || 'v' }}'
+          reason="Stable Release (main tagged release)"
           save_package_artifacts='${{ vars.SAVE_PACKAGE_ARTIFACTS || 'false' }}'
 
+          if [ '${{ github.event_name }}' == "workflow_dispatch" ]; then
+              reason='${{ inputs.reason }}'
+          fi
+
           # Set the outputs:
           {
               echo "package-projects=${package_projects}"
               echo "nuget-server=${nuget_server}"
+              echo "dotnet-version=${dotnet_version}"
+              echo "minver-tag-prefix=${minver_tag_prefix}"
+              echo "reason=${reason}"
               echo "save-package-artifacts=${save_package_artifacts}"
           }  >> $GITHUB_OUTPUT
 
@@ -77,5 +90,6 @@ jobs:
       dotnet-version: ${{ vars.DOTNET_VERSION }}
       package-projects: ${{ needs.get-params.outputs.package-projects }}
       nuget-server: ${{ needs.get-params.outputs.nuget-server }}
-      reason: ${{ inputs.reason }}
+      reason: ${{ needs.get-params.outputs.reason }}
       save-package-artifacts: ${{ fromJson(needs.get-params.outputs.save-package-artifacts) }}
+      minver-tag-prefix: ${{ needs.get-params.outputs.minver-tag-prefix }}

templates/AddNewPackage/content/README.md

@@ -18,7 +18,7 @@ A starter vm2 package scaffold. Customize the code, tests, benchmarks, docs, and
     dotnet run --project test/MyPackage.Tests/MyPackage.Tests.csproj`
     ```
 
-  - from **CLI**, if it is already built in **CLI** or **VSCode**  (MTP v2):
+  - from **CLI**, if it is already built in **CLI** or **VSCode** (MTP v2):
     - any OS or shell:
 
       ```bash
@@ -88,7 +88,7 @@ A starter vm2 package scaffold. Customize the code, tests, benchmarks, docs, and
     - `CONFIGURATION`: `Release`: the build configuration to use (e.g., Release or Debug)
     - `NUGET_SERVER`: `github`: the NuGet server to publish to (supported values: 'github', 'nuget', or custom URI)
     - `MINVERTAGPREFIX`: `v`: Prefix for git tags to be recognized by MinVer
-    - `SEMVER_PRERELEASE_PREFIX`: `preview`: Prefix for the prerelease tag, e.g. 'preview', 'alpha', 'beta', 'rc', etc.
+    - `MINVERDEFAULTPRERELEASEIDENTIFIERS`: `preview`: Prefix for the prerelease tag, e.g. 'preview.0', 'alpha', 'beta', 'rc', etc.
     - `SAVE_PACKAGE_ARTIFACTS`: `false`: Whether to save package artifacts after build/publish
     - `MIN_COVERAGE_PCT`: `80`%: Minimum code coverage percentage required
     - `MAX_REGRESSION_PCT`: `20`%: Maximum allowed regression percentage

templates/AddNewPackage/content/scripts/_common.diagnostics.sh

@@ -6,7 +6,6 @@ declare -ix errors=0
 ## Shell function to log error messages to the standard output and to the GitHub step summary (github_step_summary).
 ## Increments the error counter.
 ## Usage: `error <message1> [<message2> ...]`, or `echo "message" | error`, or error <<< "message"
-# shellcheck disable=SC2154 # variable is referenced but not assigned.
 function error()
 {
     if [[ $# -gt 0 ]]; then
@@ -78,6 +77,10 @@ function trace() {
 declare last_command
 declare current_command="$BASH_COMMAND"
 
+# on_debug and on_exit are trying to cooperatively do error handling when exit is invoked. To be effective, after
+# sourcing this script, set these signal traps:
+#   trap on_debug DEBUG
+#   trap on_exit EXIT
 function on_debug() {
     # keep track of the last executed command
     last_command="$current_command"

templates/AddNewPackage/content/scripts/_common.github.sh

@@ -28,7 +28,7 @@ declare -x semverTagReleaseRegex
 declare -x semverTagPrereleaseRegex
 
 ## Shell function to create the regular expressions above for tags comprising a given prefix with a semantic version.
-## Call once when the tag prefix is known. For example: create_tag_regexes "v". It might be a good idea to declare the resulting
+## Call once when the tag prefix is known. For example: create_tag_regexes 'v'. It might be a good idea to declare the resulting
 ## variables as readonly after calling this function:
 ##   declare -xr semverTagRegex
 ##   declare -xr semverTagReleaseRegex
@@ -188,7 +188,7 @@ function args_to_github_output()
 ## Validates if the first argument is a name of a valid JSON array of project paths, if it is null, empty or empty array, it use
 ## the second parameter as default value, usually `[""]`.
 # shellcheck disable=SC2154 # variable is referenced but not assigned.
-function validate_projects() {
+function are_safe_projects() {
     local -n projects=$1
     local default_projects=${2:-'[""]'}
 

templates/AddNewPackage/content/scripts/_common.predicates.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-if ! declare -pF "error" > /dev/null; then
+# shellcheck disable=SC2154 # variable is referenced but not assigned.
+if ! declare -pF "error" > "$_ignore"; then
     semver_dir="$(dirname "${BASH_SOURCE[0]}")"
     source "$semver_dir/_common.diagnostics.sh"
 fi
@@ -74,10 +75,11 @@ function is_in() {
 function has_errors()
 {
     if ((errors > 0)); then
-        error "$errors error(s) encountered. Please fix the issues and try again." >&2
         if [[ -n $1 ]]; then
-            usage
+            usage "❌  ERROR: $errors error(s) encountered. Please fix the above issues and try again."
             exit 2
+        else
+            error "$errors error(s) encountered. Please fix the above issues and try again."
         fi
         return 1
     fi
@@ -99,29 +101,29 @@ function is_git_repo()
         return 2
     fi
 
-    [[ -d $1 ]] && git -C "$1" rev-parse --is-inside-work-tree &>/dev/null
+    [[ -d $1 ]] && git -C "$1" rev-parse --is-inside-work-tree &>"$_ignore"
 }
 
 ## Tests if the current commit in the specified directory is on the latest stable tag.
 ## Usage: is_on_or_after_latest_stable_tag <directory> <stable-tag-regex> [<skip-fetch>]
 function is_latest_stable_tag()
 {
-    if [[ $# != 2 ]]; then
+    if [[ $# -lt 2 || $# -gt 3 ]]; then
         error "The function is_latest_stable_tag() takes 2 arguments: directory and regular expression for stable tag." \
               "A third argument may be specified to fetch latest in main changes from remote."
     fi
-    if [[ ! -d $1 ]]; then
+    if [[ ! -d "$1" ]]; then
         error "The specified directory '$1' does not exist."
     fi
-    if [[ -z $2 ]]; then
+    if [[ -z "$2" ]]; then
         error "The regular expression for stable tag cannot be empty."
     fi
     ((errors == 0 )) || return 2
 
     local latest_tag current_commit tag_commit
 
     is_git_repo "$1" || return 2
-    if [[ $3 != "true" ]]; then
+    if [[ $# -eq 3 && "$3" != "true" ]]; then
         git -C "$1" fetch origin main --quiet
     fi
 
@@ -131,7 +133,7 @@ function is_latest_stable_tag()
 
     current_commit=$(git -C "$1" rev-parse HEAD)
 
-    tag_commit=$(git -C "$1" rev-parse "$latest_tag^{commit}" 2>/dev/null)
+    tag_commit=$(git -C "$1" rev-parse "$latest_tag^{commit}" 2>"$_ignore")
 
     [[ "$current_commit" == "$tag_commit" ]]
 }
@@ -140,66 +142,66 @@ function is_latest_stable_tag()
 ## Usage: is_after_latest_stable_tag <directory> <stable-tag-regex> [<skip-fetch>]
 function is_after_latest_stable_tag()
 {
-    if [[ $# != 2 ]]; then
+    if [[ $# -lt 2 || $# -gt 3 ]]; then
         error "The function is_after_latest_stable_tag() takes 2 arguments: directory and regular expression for stable tag." \
               "A third argument may be specified to fetch latest in main changes from remote."
     fi
-    if [[ ! -d $1 ]]; then
+    if [[ ! -d "$1" ]]; then
         error "The specified directory '$1' does not exist."
     fi
-    if [[ -z $2 ]]; then
+    if [[ -z "$2" ]]; then
         error "The regular expression for stable tag cannot be empty."
     fi
     ((errors == 0 )) || return 2
 
     local latest_tag tag_commit commits_after
 
     is_git_repo "$1" || return 2
-    if [[ $3 != "true" ]]; then
+    if [[ $# -eq 3 && "$3" != "true" ]]; then
         git -C "$1" fetch origin main --quiet
     fi
 
     # Get latest stable tag (excludes pre-release tags with -)
     latest_tag=$(git -C "$1" tag | grep -E "$2" | sort -V | tail -n1)
     [[ -n $latest_tag ]] || return 1
 
-    tag_commit=$(git -C "$1" rev-parse "$latest_tag^{commit}" 2>/dev/null)
+    tag_commit=$(git -C "$1" rev-parse "$latest_tag^{commit}" 2>"$_ignore")
 
     # Check if current commit is after the latest stable tag
-    commits_after=$(git -C "$1" rev-list "$tag_commit..HEAD" --count 2>/dev/null)
+    commits_after=$(git -C "$1" rev-list "$tag_commit..HEAD" --count 2>"$_ignore")
     [[ $commits_after -gt 0 ]]
 }
 
 ## Tests if the current commit in the specified directory is on or after the latest stable tag.
 ## Usage: is_on_or_after_latest_stable_tag <directory> <stable-tag-regex> [<skip-fetch>]
 function is_on_or_after_latest_stable_tag()
 {
-    if [[ $# != 2 ]]; then
+    if [[ $# -lt 2 || $# -gt 3 ]]; then
         error "The function is_on_or_after_latest_stable_tag() takes 2 arguments: directory and regular expression for stable tag." \
               "A third argument may be specified to fetch latest in main changes from remote."
     fi
-    if [[ ! -d $1 ]]; then
+    if [[ ! -d "$1" ]]; then
         error "The specified directory '$1' does not exist."
     fi
-    if [[ -z $2 ]]; then
+    if [[ -z "$2" ]]; then
         error "The regular expression for stable tag cannot be empty."
     fi
     ((errors == 0 )) || return 2
 
     local latest_tag tag_commit
 
     is_git_repo "$1" || return 2
-    if [[ $3 != "true" ]]; then
+    if [[ $# -eq 3 && "$3" != "true" ]]; then
         git -C "$1" fetch origin main --quiet
     fi
 
     # Get latest stable tag
     latest_tag=$(git -C "$1" tag | grep -E "$2" | sort -V | tail -n1)
     [[ -n $latest_tag ]] || return 1
 
-    tag_commit=$(git -C "$1" rev-parse "$latest_tag^{commit}" 2>/dev/null)
+    tag_commit=$(git -C "$1" rev-parse "$latest_tag^{commit}" 2>"$_ignore")
 
     # Check if current commit is on or after the latest stable tag
     # Returns 0 if tag commit is an ancestor of HEAD (i.e., HEAD is at or after the tag)
-    git -C "$1" merge-base --is-ancestor "$tag_commit" HEAD &>/dev/null
+    git -C "$1" merge-base --is-ancestor "$tag_commit" HEAD &>"$_ignore"
 }