Merge branch 'feat/support-commit-specifications' into 'master'

feat: add support for defining a commit specification, e.g., conventional commits

Closes #39

See merge request to-be-continuous/semantic-release!52

README.md

@@ -185,6 +185,29 @@ This job can be enabled by defining the `SEMREL_INFO_ON` variable:
 * `protected` to enable on protected references
 * `all` to enable on all Git references. :warning: Beware that this job requires the `GITLAB_TOKEN` variable so you must unprotect it (this will make privilege escalation possible from developer to maintainer).
 
+#### Semantic Release Commit Analyzer and Release Notes Configuration
+
+Semantic Release determines the semantic version, major.minor.patch, with the use of `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator` `presets`. The [**default** preset is `angular`](https://github.com/semantic-release/semantic-release?tab=readme-ov-file#commit-message-format).
+The default _may_ lead to unexpected versioning or release notes, especially when not in an Angular project nor using the Angular standard.
+
+The commit message parser may be changed by defining the `commit-spec` / `SEMREL_COMMIT_SPEC` variable:
+
+| Input / Variable                            | Description | Default |
+| ------------------------------------------- | ----------- | ------- |
+| `commit-spec` / `SEMREL_COMMIT_SPEC` | commit specification `preset` (possible values: `angular`, `codemirror`, `ember`, `eslint`, `express`, `jquery`, `jshint`, `conventionalcommits` (`cc` short form supported)) | `angular` |
+
+**Conventional Commit Specification**
+
+The `preset` of `conventionalcommits` (or `cc`) is a good option for most users. The [specification is well defined and documented](https://www.conventionalcommits.org/en/v1.0.0/) and compatible with tools like [Husky](https://typicode.github.io/husky/) and [commitlint](https://commitlint.js.org/). Semantic Release has plans to make `conventionalcommits` the default in the future.
+
+**Commit Message Controls**
+
+The `commit-spec` / `SEMREL_COMMIT_SPEC` value installs the parser requirement for Semantic Release only. Adherence to a specification with commit message controls is not provided. Angular and Conventional Commits are widely supported by commitlint and [commitizen](https://github.com/commitizen), though additional `devDependencies` and configuration files may be required, please review the tooling documentation for more information. 
+
+**Note on supporting Semantic Release versions**
+
+If the version of Semantic Release is pinned using [`SEMREL_VERSION`](#global-configuration) prior to v24, automated versioning via commit messaging may fail in unexpected ways. See [conventional-changelog-conventionalcommits v8.0.0 breaks semantic release](https://github.com/semantic-release/release-notes-generator/issues/633) or consider upgrading the pinned version to v24 or better to restore behaviors.
+
 ## Secrets management
 
 Here are some advices about your **secrets** (variables marked with a :lock:):

kicker.json

@@ -105,6 +105,13 @@
           "name": "SEMREL_COMMIT_MESSAGE",
           "description": "[message @semantic-release/git option](https://github.com/semantic-release/git#message)",
           "advanced": true
+        },
+        {
+          "name": "SEMREL_COMMIT_SPEC",
+          "description": "Commit specification `preset` (possible values: `angular`, `atom`, `codemirror`, `ember`, `eslint`, `express`, `jquery`, `jshint`, `conventionalcommits`). The default is `angular`.",
+          "values": ["angular","codemirror","conventionalcommits","ember","eslint","express","jquery","jshint"],
+          "default": "angular",          
+          "advanced": true
         }
       ]
     },

templates/gitlab-ci-semrel.yml

@@ -65,6 +65,18 @@ spec:
     commit-message:
       description: '[message @semantic-release/git option](https://github.com/semantic-release/git#message)'
       default: ''
+    commit-spec:
+      description: "Commit specification `preset` (possible values: `angular`, `codemirror`, `ember`, `eslint`, `express`, `jquery`, `jshint`, `conventionalcommits`). The default is `angular`."
+      options:
+      - angular
+      - codemirror
+      - conventionalcommits
+      - ember
+      - eslint
+      - express
+      - jquery
+      - jshint
+      default: 'angular'
     info-on:
       description: Define on which branch(es) the job shall be run
       options:
@@ -129,6 +141,7 @@ variables:
   SEMREL_COMMIT_MESSAGE: $[[ inputs.commit-message ]]
   SEMREL_RELEASE_DISABLED: $[[ inputs.release-disabled ]]
   SEMREL_INFO_ON: $[[ inputs.info-on ]]
+  SEMREL_COMMIT_SPEC: $[[ inputs.commit-spec ]]
 
   # default production ref name (pattern)
   PROD_REF: /^(master|main)$/
@@ -480,6 +493,7 @@ stages:
         else
           debug="false"
         fi
+        commitPresetConfig=$(generate_commit_preset_conf)
         changelogPluginConfig=$(generate_changelog_plugin_conf)
         execPluginConfig=$(generate_exec_plugin_conf)
         gitPluginConfig=$(generate_git_plugin_conf)
@@ -489,8 +503,10 @@ stages:
           echo "tagFormat: '${SEMREL_TAG_FORMAT}'"
           echo ""
           echo "plugins: "
-          echo "  - '@semantic-release/commit-analyzer'"
-          echo "  - '@semantic-release/release-notes-generator'"
+          echo "  - - '@semantic-release/commit-analyzer'"
+          echo "${commitPresetConfig}"
+          echo "  - - '@semantic-release/release-notes-generator'"
+          echo "${commitPresetConfig}"
           echo "  - '@semantic-release/gitlab'"
           echo "${changelogPluginConfig}"
           echo "${execPluginConfig}"
@@ -523,7 +539,33 @@ stages:
     done <<< $(yq eval ".plugins[]" "${semrelConfigFile}" -o=json --indent 0)
 
     # shellcheck disable=SC2086
-    npm install -g "semantic-release@${SEMREL_VERSION}" ${required_plugins}
+    npm install --global "semantic-release@${SEMREL_VERSION}" ${required_plugins}
+    
+    if [[ ! -f "${SEMREL_REQUIRED_PLUGINS_FILE}" && -n "${SEMREL_COMMIT_SPEC}" ]]; then
+      case "$SEMREL_COMMIT_SPEC" in
+        cc)
+          SEMREL_COMMIT_SPEC=conventionalcommits
+          ;;
+      esac
+      npm install --global "conventional-changelog-$SEMREL_COMMIT_SPEC" 
+    fi
+
+    if [[ -n "$TRACE" ]]; then
+        log_info "Installed devDependencies..."
+        npm pkg get devDependencies
+        log_info "Globally installed packages..."
+        npm list --global
+      fi
+  }
+
+  # this script console output is inserted in generated file: DO NOT ADD LOGS
+  function generate_commit_preset_conf() {
+    if [[ -n "${SEMREL_COMMIT_SPEC}" ]]; then
+      if [[ "${SEMREL_COMMIT_SPEC}" == "cc" ]]; then
+        conventionalCommits="conventionalcommits"  
+      fi   
+      echo "    - preset: '${conventionalCommits:-$SEMREL_COMMIT_SPEC}'"
+    fi
   }
   
   # this script console output is inserted in generated file: DO NOT ADD LOGS
@@ -700,7 +742,7 @@ stages:
       cat ".releaserc"
     fi
 
-    npm install -g "semantic-release@${SEMREL_VERSION}" "@semantic-release/exec@${SEMREL_EXEC_VERSION}"
+    npm install --global "semantic-release@${SEMREL_VERSION}" "@semantic-release/exec@${SEMREL_EXEC_VERSION}"
     semantic-release --dry-run
 
     # Rollback temporary semantic-release configuration