@ethima/semantic-release-configuration 4.0.1 → 4.1.1

package/README.md

@@ -68,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
 
@@ -232,6 +301,8 @@ release by hand from the tag and changelog that was created by the
 [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
@@ -245,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.1",
+  "version": "4.1.1",
   "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"
@@ -18,12 +21,15 @@
   },
   "homepage": "https://gitlab.com/ethima/semantic-release-configuration#readme",
   "dependencies": {
-    "@google/semantic-release-replace-plugin": "1.2.0",
+    "@google/semantic-release-replace-plugin": "1.2.5",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
     "@semantic-release/github": "9.0.3",
     "@semantic-release/gitlab": "12.0.3",
-    "conventional-changelog-conventionalcommits": "6.0.0",
+    "conventional-changelog-conventionalcommits": "6.1.0",
     "cosmiconfig": "8.2.0"
+  },
+  "devDependencies": {
+    "ava": "5.3.1"
   }
 }

package/src/branches.js

@@ -0,0 +1,82 @@
+/**
+ * Determines the type of branch for the provided `branch`, i.e. whether it
+ * represents a "maintenance" or a "prerelease" branch.
+ *
+ * @return object The `branch_prefix` and whether it `is_prerelease`.
+ */
+function determinePrefixedBranchType(
+  branch,
+  { maintenance_branch_prefix, prerelease_branch_prefix }
+) {
+  if (branch.startsWith(maintenance_branch_prefix)) {
+    return { branch_prefix: maintenance_branch_prefix, is_prerelease: false };
+  } else {
+    return { branch_prefix: prerelease_branch_prefix, is_prerelease: true };
+  }
+}
+
+/**
+ * Determines the "branches" for a semantic-release configuration given the
+ * provided `configuration` for the shareable configuration. This ensures more
+ * (patterned) release branches can be supported than would typically be the
+ * case.
+ *
+ * The function is capable of dealing with "primary release branches", the
+ * corresponding "prerelease branch", and patterned "maintenance" and
+ * "prerelease" branches.
+ *
+ * @return array An array containing the determined branch configuration as the
+ * sole entry.
+ */
+function BranchesConfiguration(branch, configuration) {
+  if (configuration.primary_release_branch === branch) {
+    return [branch];
+  }
+
+  if (configuration.prerelease_branch_prefix === branch) {
+    return [
+      configuration.primary_release_branch,
+      { name: branch, prerelease: configuration.prerelease_tag_suffix },
+    ];
+  }
+
+  const { branch_prefix, is_prerelease } = determinePrefixedBranchType(
+    branch,
+    configuration
+  );
+
+  // The matching pattern is configured to match all allowed permutations of
+  // version specifications as closely as possible to ensure other permutations
+  // that look valid, e.g. `N.z.q`, do not also accidentally match
+  const branch_prefix_separator = configuration.branch_prefix_separator ?? "-";
+  const version_branch_matcher = new RegExp(
+    `^${branch_prefix}${branch_prefix_separator}(?<major>\\d+)(?<minor>\\.(\\d+|x|y))?(\\.(x|z))?$`
+  );
+  if (version_branch_matcher.test(branch)) {
+    let {
+      groups: { major, minor },
+    } = branch.match(version_branch_matcher);
+
+    // Remove minor parts not representing digits, so they are not included in
+    // the returned `range`
+    const version_part_matcher = new RegExp("\\.\\d+");
+    if (!version_part_matcher.test(minor)) {
+      minor = "";
+    }
+
+    return [
+      configuration.primary_release_branch,
+      {
+        name: branch,
+        ...(is_prerelease
+          ? { prerelease: configuration.prerelease_tag_suffix }
+          : {}),
+        range: `${major}${minor}.x`,
+      },
+    ];
+  }
+
+  return [];
+}
+
+module.exports = BranchesConfiguration;

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");
 
@@ -69,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",