diff --git a/README.md b/README.md index 260e3837067a5837eedd86fcf8c9a55c7e3ccfa0..bbdfe3b21f4b40563fb962fd12b76e0dee2684ed 100644 --- a/README.md +++ b/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:): diff --git a/kicker.json b/kicker.json index bb36841be5a515ecab3123f733e32d2f1122d790..7a89db0d054d0bc325925f0282ca4675fa98aa42 100644 --- a/kicker.json +++ b/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 } ] }, diff --git a/templates/gitlab-ci-semrel.yml b/templates/gitlab-ci-semrel.yml index 49d1eec045aa9a3c97dd25c2e9a1897633693d7a..4c21159837b47c835fd200c9d4b66fbe6acf2f58 100644 --- a/templates/gitlab-ci-semrel.yml +++ b/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,9 +539,35 @@ 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 function generate_changelog_plugin_conf() { if [[ "${SEMREL_CHANGELOG_ENABLED}" = "true" ]]; then @@ -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