@ethima/semantic-release-configuration 4.0.0 → 4.1.0

package/README.md

@@ -35,9 +35,12 @@ configuration supporting a range of languages and platforms supported by the
 
 ## Usage
 
-- Create the relevant secret token for the platform on which the project
-  using this configuration is hosted, e.g. `GH_TOKEN`, `GITLAB_TOKEN`. The
-  supported platforms are [GitHub][semantic-release-github-plugin-auth-url] and
+- Create the [relevant authentication
+  token][semantic-release-authentication-url] for the platform on which the
+  project using this configuration is hosted. This secret will be used by the
+  main `semantic-release` tool for pushing tags as well as the
+  platform-specific plugin i.e.
+  [GitHub][semantic-release-github-plugin-auth-url] or
   [GitLab][semantic-release-gitlab-plugin-auth-url].
 
   For improved security, _use a unique token for every project this
@@ -65,16 +68,85 @@ for this purpose. This library will search for an `ethima` configuration file
 as explained in the introduction of its `README`, e.g. a JSON or YAML-formatted
 `.ethimarc` or `.config/ethimarc` file, JavaScript in a `.ethimarc.js`, etc.
 
-Generic configuration options are:
+The available configuration options are explained in detail in the sections
+describing the functionality they apply to.
 
-- `primary_release_branch` a string indicating the "primary" release branch,
-  i.e. the branch from which new releases should be created. This may also be
-  specified as a `PRIMARY_RELEASE_BRANCH` environment variable and will default
-  to [the `CI_DEFAULT_BRANCH` on GitLab][gitlab-predefined-variables-url] and
-  to `main` on other platforms.
+### Branches
+
+By default, `semantic-release` accepts [_at most_ 3 "release
+branches"][semantic-release-branches-url]. This configuration provides a
+mechanism to work around this limitation by detecting the type of the active
+branch and only configuring `semantic-release` to act on the primary release
+branch and the active branch, enabling the use of more "release branches". The
+primary release branch is _always_ configured as `semantic-release` requires at
+least one "release branch" to be defined.
+
+Additionally, this configuration extends the allowed patterns for "maintenance"
+and "prerelease" branches. Specifically `semantic-release` only supports
+[`N.N.x`, `N.x.x` and `N.x` patterns][semantic-release-branch-patterns-url]
+where `N` is a number. When using this configuration `N`, `N.N`, `N.y`, `N.y.z`
+and `N.N.z` (suffix) patterns are also supported.
+
+The configuration distinguishes three types of branches:
+
+- The "primary release branch" which is the branch from which the most
+  up-to-date release gets cut.
+- "Maintenance branches" which represent a specific subset of releases that can
+  be used for maintenance releases after the "primary release branch" has moved
+  ahead to a newer version. For instance, a `release-2` branch when the primary
+  release branch targets releases for version 3 or up, or a `release-1.2`
+  branch for releases within the v1.2.z range after the `release-1` branch has
+  started to target v1.3.z.
+- "Prerelease branches" which can be used to "gate" releases, e.g. to
+  accumulate a number of changes to release at once instead of releasing on
+  every single merge into a "release branch", i.e. the "primary release branch"
+  or a "maintenance branch". These branches typically follow the naming
+  convention of the other "release branches" but with a different prefix, e.g.
+  `next-2` corresponds to prereleases for `release-2`, `next-1.2.z` corresponds
+  to releases for `release-1.2.z`, etc. The "prerelease branch" for the
+  "primary release branch" is a special case which only consists of the prefix
+  used to indicate "prerelease branches", e.g. `next`. The tags associated with
+  a "prerelease branch" receive an additional suffix.
+
+  Note that "breaking" or "feature" "prerelease branches" will accept
+  prereleases for the next "breaking" or "feature" version as, according to the
+  [semantic versioning
+  specification][semantic-versioning-prerelease-precedence-url], these versions
+  technically fall within the upper bounded version range represented by the
+  "prerelease branch". For instance, a feature commit on the `next-3.1` branch
+  will be accepted and results in the publication of `3.2.0-rc.1` from that
+  branch. If that same commit would have been made on the `release-3.1` branch
+  it would not have been accepted.
+
+Various aspects of branch and tag naming can be configured through the
+mechanisms [outlined above](#configuration). The folowing branch-related
+configuration options are available:
+
+| Configuration option        | Description                                                                         | Environment Variable        |
+| --------------------------- | ----------------------------------------------------------------------------------- | --------------------------- |
+| `branch_prefix_separator`   | Specifies the character(s) used to separate the branch prefixes from version ranges | `BRANCH_PREFIX_SEPARATOR`   |
+| `maintenance_branch_prefix` | Specifies the prefix used for "maintenance branches"                                | `MAINTENANCE_BRANCH_PREFIX` |
+| `prerelease_branch_prefix`  | Specifies the prefix used for "prerelease branches"                                 | `PRERELEASE_BRANCH_PREFIX`  |
+| `prerelease_branch_prefix`  | Specifies the suffix used for tags created from "prerelease branches"               | `PRERELEASE_TAG_SUFFIX`     |
+| `primary_release_branch`    | Indicates the name of the "primary release branch"                                  | `PRIMARY_RELEASE_BRANCH`    |
+
+The default configuration is
+
+```js
+{
+  branch_prefix_separator: "-",
+  maintenance_branch_prefix: "release"
+  prerelease_branch_prefix: "next",
+  prerelease_tag_suffix: "rc",
+  primary_release_branch: env.CI_DEFAULT_BRANCH || "main",
+}
+```
 
-Other configuration options are explained in more detail in the sections
-describing the functionality they apply to.
+The branch for which a release is intended to be triggered should be provided
+as a `CURRENT_BRANCH` environment variable before instantiating this
+configuration. For common platforms, i.e. GitLab CI and GitHub Actions, this
+value will be automatically derived from known environment variables specific
+to each platform.
 
 ### Changelog Maintenance
 
@@ -228,6 +300,9 @@ release by hand from the tag and changelog that was created by the
 [juliahub-register-package-url]: https://juliahub.com/ui/Registrator
 [npm-token-url]: https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website
 [replace-in-file-url]: https://www.npmjs.com/package/replace-in-file
+[semantic-release-authentication-url]: https://semantic-release.gitbook.io/semantic-release/usage/ci-configuration#authentication
+[semantic-release-branch-patterns-url]: https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#range
+[semantic-release-branches-url]: https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#release-branches
 [semantic-release-changelog-plugin-url]: https://github.com/semantic-release/changelog
 [semantic-release-commit-analyzer-plugin-url]: https://github.com/semantic-release/commit-analyzer
 [semantic-release-extends-configuration-url]: https://semantic-release.gitbook.io/semantic-release/usage/configuration#extends
@@ -241,3 +316,4 @@ release by hand from the tag and changelog that was created by the
 [semantic-release-npm-plugin-url]: https://www.npmjs.com/package/@semantic-release/npm
 [semantic-release-replace-plugin-url]: https://github.com/google/semantic-release-replace-plugin
 [semantic-release-url]: https://semantic-release.gitbook.io/
+[semantic-versioning-prerelease-precedence-url]: https://semver.org/#spec-item-9

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@ethima/semantic-release-configuration",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "A shareable semantic release configuration supporting a range of languages and platforms supported by the Ethima organization.",
   "main": "./src/index.js",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@gitlab.com/ethima/semantic-release-configuration.git"
   },
+  "scripts": {
+    "test": "ava"
+  },
   "keywords": [
     "Semantic",
     "Release"
@@ -21,9 +24,12 @@
     "@google/semantic-release-replace-plugin": "1.2.0",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
-    "@semantic-release/github": "8.0.7",
-    "@semantic-release/gitlab": "12.0.1",
-    "conventional-changelog-conventionalcommits": "5.0.0",
-    "cosmiconfig": "8.1.3"
+    "@semantic-release/github": "9.0.3",
+    "@semantic-release/gitlab": "12.0.3",
+    "conventional-changelog-conventionalcommits": "6.1.0",
+    "cosmiconfig": "8.2.0"
+  },
+  "devDependencies": {
+    "ava": "5.3.1"
   }
 }

package/src/configuration.js

@@ -2,8 +2,17 @@ const { cosmiconfigSync } = require("cosmiconfig");
 const { env } = require("node:process");
 
 const CONFIGURATION_DEFAULTS = {
+  // The character(s) to use to separate the prefix for maintenance and
+  // prerelease branches from the version pattern
+  branch_prefix_separator: env.BRANCH_PREFIX_SEPARATOR || "-",
   changelog_filename: "CHANGELOG.md",
   files_with_versioned_templates: ["README.md"],
+  // The branch prefix for patterned maintenance branches
+  maintenance_branch_prefix: env.MAINTENANCE_BRANCH_PREFIX || "release",
+  // The branch prefix for patterned prerelease branches
+  prerelease_branch_prefix: env.PRERELEASE_BRANCH_PREFIX || "next",
+  // The tag suffix to use for tags created from prerelease branches
+  prerelease_tag_suffix: env.PRERELEASE_TAG_SUFFIX || "rc",
   // The `PRIMARY_RELEASE_BRANCH` environment variable is used as a platform
   // independent mechanism for specifying the primary release branch. On GitLab
   // this defaults to the "default" branch. Given that the "default" branch is

package/src/index.js

@@ -1,6 +1,7 @@
 const { accessSync } = require("node:fs");
 const { env } = require("node:process");
 
+const BranchesConfiguration = require("./branches.js");
 const CONFIGURATION = require("./configuration.js");
 const VersionedTemplatesConfiguration = require("./versioned-templates.js");
 
@@ -9,25 +10,19 @@ const GIT_ASSETS = [
   ...CONFIGURATION.files_with_versioned_templates,
 ];
 
-// Used to detect whether configuration for either the
-// `semantic-release/github`, `semantic-release/gitlab` or both platform
-// release plugins has been provided through the environment
-const GITHUB_TOKEN_NAMES = ["GH_TOKEN", "GITHUB_TOKEN"];
-const GITLAB_TOKEN_NAMES = ["GL_TOKEN", "GITLAB_TOKEN"];
-
 /*
  * Determines whether the provided plugin should be added to the semantic
  * release configuration based on the presence of select environment variables.
  *
- * @param {Array} token_names An array of strings specifying the names of the
- * environment variables to detect.
+ * @param {string} environment_variable The environment variable to verify the
+ * existence of (and equality to `"true"`) to include the specified `plugin`.
  * @param {string} plugin The name of the NPM package providing the plugin.
  *
- * @return {Array} References the plugin if any of the `token_names` are
- * detected and is empty otherwise.
+ * @return {Array} References the plugin if the `environment_variable` was set
+ * to `"true"` and is empty otherwise.
  */
-function platformSpecificReleasePlugin(token_names, plugin) {
-  return token_names.some((token_name) => env[token_name]) ? [plugin] : [];
+function platformSpecificReleasePlugin(environment_variable, plugin) {
+  return env[environment_variable] === "true" ? [plugin] : [];
 }
 
 // Ensure the NPM plugin gets added to the semantic release pipeline if a
@@ -75,8 +70,14 @@ try {
   ]);
 } catch {}
 
+// Determine the current branch based off well-known environment variables
+// typically available in CI, i.e. Ethima specific configuration, GitLab CI,
+// and GitHub Actions
+const current_branch =
+  env.CURRENT_BRANCH ?? env.CI_COMMIT_REF_NAME ?? env.GITHUB_REF_NAME;
+
 const SEMANTIC_RELEASE_CONFIGURATION = {
-  branches: [CONFIGURATION.primary_release_branch],
+  branches: BranchesConfiguration(current_branch, CONFIGURATION),
   plugins: [
     ["@semantic-release/commit-analyzer", { preset: "conventionalcommits" }],
     "@semantic-release/release-notes-generator",
@@ -101,13 +102,10 @@ const SEMANTIC_RELEASE_CONFIGURATION = {
       },
     ],
     ...platformSpecificReleasePlugin(
-      GITHUB_TOKEN_NAMES,
+      "GITHUB_ACTIONS",
       "@semantic-release/github"
     ),
-    ...platformSpecificReleasePlugin(
-      GITLAB_TOKEN_NAMES,
-      "@semantic-release/gitlab"
-    ),
+    ...platformSpecificReleasePlugin("GITLAB_CI", "@semantic-release/gitlab"),
   ],
 };