@ethima/semantic-release-configuration 2.0.0 → 2.1.1

package/README.md

@@ -36,6 +36,30 @@ configuration supporting a range of languages and platforms supported by the
   [`extends`][semantic-release-extends-configuration-url] configuration for the
   project to be semantically released.
 
+### Configuration
+
+The semantic release configuration has several configuration options itself.
+Some of this configuration, like sensitive tokens such as `GITLAB_TOKEN` and
+`NPM_TOKEN`, should be configured through environment variables.
+
+Other configuration options have more complex values and are not suitable for
+configuration through environment variables. These configuration options can be
+configured through a file. The [`cosmiconfig` library][cosmiconfig-url] is used
+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.
+
+All configuration options are explained in more detail in the sections
+describing the functionality they apply to.
+
+### Changelog Maintenance
+
+A changelog is maintained using the release notes generated by the semantic
+release tooling. This changelog is maintained in a `CHANGELOG.md` in the root
+of a project by default. This path can be configured by adding a
+`changelog_filename` property to a file-based configuration as described in
+[the configuration section](#configuration).
+
 ### JavaScript Packages
 
 JavaScript packages are detected based on the presence of a `package.json` file
@@ -66,7 +90,7 @@ structure:
 
 ` token,
 - the template itself with one or more
-  `2.0.0` tokens,
+  `2.1.1` tokens,
 - a comment closing tag `
 
 <!-- END_VERSIONED_TEMPLATE -->`.
@@ -80,7 +104,7 @@ The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION_
 
 -->
 
-The next semantically released version will be v2.0.0!
+The next semantically released version will be v2.1.1!
 
 <!-- END_VERSIONED_TEMPLATE -->
 ```
@@ -95,7 +119,7 @@ The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION_
 
 -->
 
-The next semantically released version will be v2.0.0!
+The next semantically released version will be v2.1.1!
 
 <!-- END_VERSIONED_TEMPLATE -->
 ```
@@ -103,6 +127,44 @@ The next semantically released version will be v2.0.0!
 Note that the `v` is in the template! The version as derived by the semantic
 release tooling does not contain that prefix.
 
+#### Configuring which files to update
+
+The templated content feature uses [the `replace-in-file`
+library][replace-in-file-url] to perform the actual replacements. In which
+files templates should be replaced, can be configured by adding a
+`files_with_versioned_templates` key specifying an array of filenames and globs
+to a configuration file as described in the [configuration
+section](#configuration). For instance:
+
+```json
+{
+  "files_with_versioned_templates": [
+    "README.md",
+    "some/other/file.md",
+    "a/glob/for/multiple/markdown/files/*.md",
+    "src/**/*.js"
+  ]
+}
+```
+
+#### Preventing individual templates from being updated
+
+Configuring which files to ignore when updating templated content is a very
+coarse approach which may not always be suitable. In cases where a more
+fine-grained approach is necessary, replacements in individual templates can be
+prevented by modifying (one of) the tokens in those templates. For instance by
+including a non-visible whitespace character, e.g. [a _Zero Width Non-Joiner
+(ZWNJ)_ character](https://unicode-table.com/en/200C/). A sufficient approach
+is to modify the starting token, so that the template is no longer recognized
+as one. Using the suggested ZWNJ character the starting token becomes
+`<!--‌ START_VERSIONED_TEMPLATE`.
+
+Note that when using this approach, although the templates/tokens _visually_
+look like versions that should be replaced, they cannot be copied and pasted as
+examples as the resulting copies will also contain the non-visible whitespace
+character. When using this approach be sure to indicate this as to not confuse
+readers as to why replacements may not be working!
+
 ## Troubleshooting
 
 ### Publishing the initial release of a scoped JavaScript package
@@ -123,8 +185,10 @@ 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.
 
+[cosmiconfig-url]: https://www.npmjs.com/package/cosmiconfig
 [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
+[replace-in-file-url]: https://www.npmjs.com/package/replace-in-file
 [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethima/semantic-release-configuration",
-  "version": "2.0.0",
+  "version": "2.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": {
@@ -21,6 +21,7 @@
     "@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"
+    "@semantic-release/gitlab": "9.5.1",
+    "cosmiconfig": "8.0.0"
   }
 }

package/src/configuration.js

@@ -0,0 +1,16 @@
+const { cosmiconfigSync } = require("cosmiconfig");
+
+const CONFIGURATION_DEFAULTS = {
+  changelog_filename: "CHANGELOG.md",
+  files_with_versioned_templates: ["README.md"],
+};
+
+const ethimaConfig = cosmiconfigSync("ethima").search();
+
+// The configuration only supports merging elements at the root object. This is
+// sufficient for the current configuration needs, which tend to be simple
+// values and doing a deep merge would add currently unnecessary complexity.
+// This can be revisited once the need arises
+const CONFIGURATION = { ...CONFIGURATION_DEFAULTS, ...ethimaConfig?.config };
+
+module.exports = CONFIGURATION;

package/src/index.js

@@ -1,12 +1,13 @@
 const { accessSync } = require("node:fs");
 const { env } = require("node:process");
 
+const CONFIGURATION = require("./configuration.js");
 const VersionedTemplatesConfiguration = require("./versioned-templates.js");
 
-const CHANGELOG_FILENAME = "CHANGELOG.md";
-const README_FILENAME = "README.md";
-
-const GIT_ASSETS = [CHANGELOG_FILENAME, README_FILENAME];
+const GIT_ASSETS = [
+  CONFIGURATION.changelog_filename,
+  ...CONFIGURATION.files_with_versioned_templates,
+];
 
 // Ensure the NPM plugin gets added to the semantic release pipeline if a
 // `package.json` file is detected
@@ -24,9 +25,14 @@ const SEMANTIC_RELEASE_CONFIGURATION = {
     "@semantic-release/release-notes-generator",
     [
       "@semantic-release/changelog",
-      { changelogFile: CHANGELOG_FILENAME, changelogTitle: "# Changelog" },
+      {
+        changelogFile: CONFIGURATION.changelog_filename,
+        changelogTitle: "# Changelog",
+      },
     ],
-    VersionedTemplatesConfiguration(README_FILENAME),
+    VersionedTemplatesConfiguration(
+      CONFIGURATION.files_with_versioned_templates
+    ),
     ...NPM_PLUGIN,
     [
       "@semantic-release/git",