@ethima/semantic-release-configuration 2.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2022 Joris Kraak <me@joriskraak.nl>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# Semantic Release Configuration
+
+A shareable [semantic release](https://semantic-release.gitbook.io)
+configuration supporting a range of languages and platforms supported by the
+@ethima organization.
+
+## Features
+
+- Analyzes commits using
+  [`@semantic-release/commit-analyzer`][semantic-release-commit-analyzer-plugin-url].
+- Generates release notes using
+  [`@semantic-release/release-notes-generator`][semantic-release-notes-generator-plugin-url].
+- Updates templated content in a project's root-level `README.md` file
+  with updated version information using
+  [`@google/semantic-release-replace-plugin`][semantic-release-replace-plugin-url]
+  and [`@semantic-release/git`][semantic-release-git-plugin-url].
+- Maintains a `CHANGELOG.md` from the generated release notes using
+  [`@semantic-release/changelog`][semantic-release-changelog-plugin-url] and
+  [`@semantic-release/git`][semantic-release-git-plugin-url].
+- (Conditionally) maintains NPM package files, i.e. `package.json` and
+  publishes using [`@semantic-release/npm`][semantic-release-npm-plugin-url]
+  and [`@semantic-release/git`][semantic-release-git-plugin-url].
+- Publishes releases to GitLab using
+  [`@semantic-release/gitlab`][semantic-release-gitlab-plugin-url].
+
+## Usage
+
+- Create a [personal access token][gitlab-pat-url], with `api` and
+  `write_repository` scopes. Make the token available as a `GITLAB_TOKEN` or
+  `GL_TOKEN` CI/CD variable of the project using the configuration.
+
+  For improved security, _use a unique token for every project this
+  configuration is used in_!
+
+- Use this shareable semantic release configuration by including it in the
+  [`extends`][semantic-release-extends-configuration-url] configuration for the
+  project to be semantically released.
+
+### JavaScript Packages
+
+JavaScript packages are detected based on the presence of a `package.json` file
+in the root of the project.
+
+- Create an [NPM token][npm-token-url] to be able to publish to an NPM
+  registry. Make the token available as an `NPM_TOKEN` CI/CD variable of the
+  project using the configuration.
+
+  See [the plugin's configuration
+  instructions][semantic-release-npm-plugin-configuration-url] for details and
+  alternatives.
+
+### Templated Content in `README.md` Files
+
+The configuration will look for `__NEXT_SEMANTIC_RELEASE_VERSION__` tokens in
+templates in a project's root-level `README.md` and replace them with the
+version that is being released. This is, for instance, useful for automatically
+keeping installation instructions up-to-date.
+
+Templated content is created using HTML comments and has the following
+structure:
+
+- A `<!-- START_VERSIONED_TEMPLATE` token,
+- the template itself with one or more
+  `__NEXT_SEMANTIC_RELEASE_VERSION__` tokens,
+- a comment closing tag `-->
+
+` token,
+- the template itself with one or more
+  `2.0.0` tokens,
+- a comment closing tag `
+
+<!-- END_VERSIONED_TEMPLATE -->`.
+
+More concretely a section in a `README` that looks like
+
+```markdown
+<!-- START_VERSIONED_TEMPLATE
+
+The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION__!
+
+-->
+
+The next semantically released version will be v2.0.0!
+
+<!-- END_VERSIONED_TEMPLATE -->
+```
+
+would, after a v1.2.3 release using the configuration has been triggered,
+become
+
+```markdown
+<!-- START_VERSIONED_TEMPLATE
+
+The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION__!
+
+-->
+
+The next semantically released version will be v2.0.0!
+
+<!-- END_VERSIONED_TEMPLATE -->
+```
+
+Note that the `v` is in the template! The version as derived by the semantic
+release tooling does not contain that prefix.
+
+## Troubleshooting
+
+### Publishing the initial release of a scoped JavaScript package
+
+Creating the initial release of a scoped JavaScript may fail if the package is
+intended to be public and the person creating the release not having paid for
+private packages. This results in an error similar to
+
+```
+npm ERR! 402 Payment Required - PUT https://registry.npmjs.org/@<scope>%2f<package-name> -
+You must sign up for private packages
+```
+
+When this happens, publish the initial release manually using `npm publish --access=public`
+after making sure the local copy of the project to be released is up-to-date.
+
+When this happens, it is typically also necessary to create the initial GitHub
+release by hand from the tag and changelog that was created by the
+[`semantic-release`][semantic-release-url] tooling.
+
+[gitlab-pat-url]: https://gitlab.com/-/profile/personal_access_tokens
+[npm-token-url]: https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website
+[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
+[semantic-release-git-plugin-url]: https://github.com/semantic-release/git
+[semantic-release-gitlab-plugin-url]: https://github.com/semantic-release/gitlab
+[semantic-release-notes-generator-plugin-url]: https://github.com/semantic-release/release-notes-generator
+[semantic-release-npm-plugin-configuration-url]: https://github.com/semantic-release/npm#npm-registry-authentication
+[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/

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@ethima/semantic-release-configuration",
+  "version": "2.0.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"
+  },
+  "keywords": [
+    "Semantic",
+    "Release"
+  ],
+  "author": "Joris Kraak <me@joriskraak.nl>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://gitlab.com/ethima/semantic-release-configuration/issues"
+  },
+  "homepage": "https://gitlab.com/ethima/semantic-release-configuration#readme",
+  "dependencies": {
+    "@google/semantic-release-replace-plugin": "1.2.0",
+    "@semantic-release/changelog": "6.0.2",
+    "@semantic-release/git": "10.0.1",
+    "@semantic-release/gitlab": "9.5.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,43 @@
+const { accessSync } = require("node:fs");
+const { env } = require("node:process");
+
+const VersionedTemplatesConfiguration = require("./versioned-templates.js");
+
+const CHANGELOG_FILENAME = "CHANGELOG.md";
+const README_FILENAME = "README.md";
+
+const GIT_ASSETS = [CHANGELOG_FILENAME, README_FILENAME];
+
+// Ensure the NPM plugin gets added to the semantic release pipeline if a
+// `package.json` file is detected
+const NPM_PLUGIN = [];
+try {
+  accessSync("package.json");
+  GIT_ASSETS.push("package.json");
+  NPM_PLUGIN.push("@semantic-release/npm");
+} catch {}
+
+const SEMANTIC_RELEASE_CONFIGURATION = {
+  branches: [env.CI_DEFAULT_BRANCH],
+  plugins: [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      { changelogFile: CHANGELOG_FILENAME, changelogTitle: "# Changelog" },
+    ],
+    VersionedTemplatesConfiguration(README_FILENAME),
+    ...NPM_PLUGIN,
+    [
+      "@semantic-release/git",
+      {
+        assets: GIT_ASSETS,
+        message:
+          "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}",
+      },
+    ],
+    "@semantic-release/gitlab",
+  ],
+};
+
+module.exports = SEMANTIC_RELEASE_CONFIGURATION;

package/src/versioned-templates.js

@@ -0,0 +1,56 @@
+const BLOCK_COMMENT_END_PATTERN = "-->";
+const BLOCK_COMMENT_START_PATTERN = "<!--";
+const TEMPLATE_VERSION_PLACEHOLDER = "__NEXT_SEMANTIC_RELEASE_VERSION__";
+
+const templateMatcher = new RegExp(
+  [
+    `(${BLOCK_COMMENT_START_PATTERN}\\s*START_VERSIONED_TEMPLATE\\s*)`,
+    "(.*?)", // The template to insert the version into
+    `(\\s*${BLOCK_COMMENT_END_PATTERN})`,
+    ".*?", // The templated content, will be discarded
+    `(${BLOCK_COMMENT_START_PATTERN}\\s*END_VERSIONED_TEMPLATE\\s*${BLOCK_COMMENT_END_PATTERN})`,
+  ].join(""),
+  "gms"
+);
+
+function templateReplacer(
+  _,
+  templateStartMarker,
+  template,
+  templateEndMarker,
+  templateCloseMarker,
+  ...args
+) {
+  const context = args.pop();
+
+  return [
+    templateStartMarker,
+    template,
+    templateEndMarker,
+    `\n\n`,
+    template.replaceAll(
+      TEMPLATE_VERSION_PLACEHOLDER,
+      context.nextRelease.version
+    ),
+    `\n\n`,
+    templateCloseMarker,
+  ].join("");
+}
+
+function VersionedTemplatesConfiguration(files) {
+  return [
+    "@google/semantic-release-replace-plugin",
+    {
+      replacements: [
+        {
+          countMatches: true,
+          files,
+          from: templateMatcher,
+          to: templateReplacer,
+        },
+      ],
+    },
+  ];
+}
+
+module.exports = VersionedTemplatesConfiguration;