build(config): generate CHANGELOG.md beautifully

Xunnamius · Nov 29, 2020 · 2fa4aa9 · 2fa4aa9
1 parent af76dbe
commit 2fa4aa9
Show file tree

Hide file tree

Showing 3 changed files with 173 additions and 59 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,108 +7,114 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [2.1.4](https://github.com/Xunnamius/workflow-playground/compare/v2.1.3...v2.1.4) (2020-11-28)
 
-
 ### Bug Fixes
 
-* **actions:** ensure metadata is gathered properly ([31ece1c](https://github.com/Xunnamius/workflow-playground/commit/31ece1cb7d0b91bbc38b1c3eb6366c13d1da7fd2))
-* **release:** remove extra newlines during changelogs generation ([72acb24](https://github.com/Xunnamius/workflow-playground/commit/72acb24c0c521217fb8eebb5204ddf1591808326))
+- **Actions:** ensure metadata is gathered properly
+  ([31ece1c](https://github.com/Xunnamius/workflow-playground/commit/31ece1cb7d0b91bbc38b1c3eb6366c13d1da7fd2))
+- **Release:** remove extra newlines during changelogs generation
+  ([72acb24](https://github.com/Xunnamius/workflow-playground/commit/72acb24c0c521217fb8eebb5204ddf1591808326))
 
 ## [2.1.3](https://github.com/Xunnamius/workflow-playground/compare/v2.1.2...v2.1.3) (2020-11-28)
 
 ### Bug Fixes
 
-- **release:** update how changelogs are generated
+- **Release:** update how changelogs are generated
   ([8ce1760](https://github.com/Xunnamius/workflow-playground/commit/8ce176044293af0ac3b5dd2495d7d0eb580bbede))
 
 ## [2.1.2](https://github.com/Xunnamius/workflow-playground/compare/v2.1.1...v2.1.2) (2020-11-28)
 
 ### Bug Fixes
 
-- **actions:** remove erroneous build-dist from lint job
+- **Actions:** remove erroneous build-dist from lint job
   ([2cdd373](https://github.com/Xunnamius/workflow-playground/commit/2cdd373974fdc62480e5681813c09cba98aebddc))
-- **actions:** remove erroneous build-dist from test-unit job
+- **Actions:** remove erroneous build-dist from test-unit job
   ([fcb2232](https://github.com/Xunnamius/workflow-playground/commit/fcb2232cf6e628f58033a78a0d6aa107f9794589))
-- **config:** fix babel.config.js with NODE_LTS
+- **Config:** fix babel.config.js with NODE_LTS
   ([cdf4610](https://github.com/Xunnamius/workflow-playground/commit/cdf46102e7d5b590bd153d2444cb13c24d4170b3))
 
 ## [2.1.1](https://github.com/Xunnamius/workflow-playground/compare/v2.1.0...v2.1.1) (2020-11-26)
 
 ### Bug Fixes
 
-- **actions:** update gather-metadata with more accurate grep
+- **Actions:** update gather-metadata with more accurate grep
   ([961ecef](https://github.com/Xunnamius/workflow-playground/commit/961ecef3555403928cf319012ca6bd40093da66e))
 
 # [2.1.0](https://github.com/Xunnamius/workflow-playground/compare/v2.0.1...v2.1.0) (2020-11-25)
 
 ### Bug Fixes
 
-- **actions:** gather-metadata steps gather and skip properly
+- **Actions:** gather-metadata steps gather and skip properly
   ([97682f4](https://github.com/Xunnamius/workflow-playground/commit/97682f434acc501e4964c31770472acae0320ad5))
-- **actions:** if statements now use | instead of >
+- **Actions:** if statements now use | instead of >
   ([24e3739](https://github.com/Xunnamius/workflow-playground/commit/24e373907b23a68627fe535049f603c93bfa1361))
-- **actions:** move comments out of multiline statements
+- **Actions:** move comments out of multiline statements
   ([874f8d6](https://github.com/Xunnamius/workflow-playground/commit/874f8d65aff5d8e27e14e8d9e4a0e37450713ce0))
 
 ### Features
 
-- **actions:** introduce new streamlined workflow job configuration
+- **Actions:** introduce new streamlined workflow job configuration
   ([4bb9d94](https://github.com/Xunnamius/workflow-playground/commit/4bb9d94050d1b8fb164bdf04b1bffa10705aa0a2))
 
 ## [2.0.1](https://github.com/Xunnamius/workflow-playground/compare/v2.0.0...v2.0.1) (2020-11-24)
 
 ### Bug Fixes
 
-- **actions:** add git author and commiter env vars for semantic-release signed
+- **Actions:** add git author and commiter env vars for semantic-release signed
   commits
   ([f01d16b](https://github.com/Xunnamius/workflow-playground/commit/f01d16b51e444eb801121e81718994b4add18799))
-- **dependabot:** ensure dependabot formats GitHub Actions PRs correctly
+- **Dependabot:** ensure dependabot formats GitHub Actions PRs correctly
   ([bcdbd0e](https://github.com/Xunnamius/workflow-playground/commit/bcdbd0e1c23786185cd43b11d9ce18d3498e9ff5))
-- add build commits to release rule
+- Add build commits to release rule
   ([3124ab0](https://github.com/Xunnamius/workflow-playground/commit/3124ab0500924ce75f3387d59d5d60ea3e77c827))
 
-# [2.0.0](https://github.com/Xunnamius/workflow-playground/compare/v1.0.15...v2.0.0) (2020-11-22)
+# [2.0.0](https://github.com/Xunnamius/workflow-playground/compare/v1.0.15...v2.0.0) (2020-11-24)
 
 ### Bug Fixes
 
-- **actions:** add install-dependencies to semantic-release needs
+- **Actions:** add install-dependencies to semantic-release needs
   ([d8cc836](https://github.com/Xunnamius/workflow-playground/commit/d8cc83611de2a595631f42bee0f10591b11bc59c))
-- **actions:** deps caching done properly
+- **Actions:** deps caching done properly
   ([bbe0416](https://github.com/Xunnamius/workflow-playground/commit/bbe0416125a303076bc3f8a5a96c9669db926b46))
-- **actions:** ensure repo is always checked out first
+- **Actions:** ensure repo is always checked out first
   ([65e5d46](https://github.com/Xunnamius/workflow-playground/commit/65e5d463925b888e08dd69a9da7f4e9f4c9be872))
-- **actions:** removed signed pushes
+- **Actions:** removed signed pushes
   ([f621f76](https://github.com/Xunnamius/workflow-playground/commit/f621f76895e6a0749f76a6a1abd90253b8694717))
-- **package.json:** do not guess error codes
+- **Package.json:** do not guess error codes
   ([f5428c8](https://github.com/Xunnamius/workflow-playground/commit/f5428c87836552db96d40310c52abd47e593e729))
-- **package.json:** ensure machine-friendly run-script syntax
+- **Package.json:** ensure machine-friendly run-script syntax
   ([7af5e45](https://github.com/Xunnamius/workflow-playground/commit/7af5e45eb0712da5d80022cedd535a673082d195))
-- **package.json:** ensure set +e used in run-scripts when necessary
+- **Package.json:** ensure set +e used in run-scripts when necessary
   ([6d86c0b](https://github.com/Xunnamius/workflow-playground/commit/6d86c0b4ce2218a93f9919a256a89a04af83a9d1))
-- **package.json:** precedence error caused bad return value in lint
+- **Package.json:** precedence error caused bad return value in lint
   ([e8bfbc5](https://github.com/Xunnamius/workflow-playground/commit/e8bfbc590ec8ac73071ae61708c1ca29f2beee36))
 
 ### Features
 
-- added diff to take the difference
+- Added diff to take the difference
   ([5e40deb](https://github.com/Xunnamius/workflow-playground/commit/5e40deb020c4bafb103a6bc78fbeecb266a5c983))
 
 ### Performance Improvements
 
-- **actions:** better caching
+- **Actions:** better caching
   ([6da0a65](https://github.com/Xunnamius/workflow-playground/commit/6da0a656aba20f022d26335ec33c9c4c4ea37c02))
-- **actions:** made test-integration-chrome independent
+- **Actions:** made test-integration-chrome independent
   ([d489cfa](https://github.com/Xunnamius/workflow-playground/commit/d489cfacd8514a210ec0b570ab3c5a283cf5bc19))
-- **actions:** only cache node_modules
+- **Actions:** only cache node_modules
   ([57775c9](https://github.com/Xunnamius/workflow-playground/commit/57775c9cc3ffdad94f09b23923785a081e2a08ee))
 
-### Reverts
+### BREAKING CHANGES
 
-- "debug: added debug step"
-  ([1741cde](https://github.com/Xunnamius/workflow-playground/commit/1741cde56623bdb6e3e0c1dc95dcbe094b197ebe))
-- db6a70c
-  ([d826682](https://github.com/Xunnamius/workflow-playground/commit/d826682b112381f0f2be55b31a1c7e0f1e8f5fea))
+- **Switch to semantic-release CI/CD pipeline.** Moved away from publish-please
+  to a fully automated build-test-deploy release cycle based on
+  semantic-release.
 
-### BREAKING CHANGES
+# Archived Releases (pre-CI/CD)
+
+- Version 1.0.15
+  ([57faa2c](https://github.com/Xunnamius/workflow-playground/commit/57faa2cc448f39383b56db04ec06b1093f5f7bcd))
+
+* Version 1.0.7
+  ([5ced626](https://github.com/Xunnamius/workflow-playground/commit/5ced6267d44731337fe5e0a69776dd5642d8a54d))
 
-- switch to semantic-release CI/CD pipeline Moved away from publish-please to a
-  fully automated build-test-deploy release cycle based on semantic-release.
+* Version 1.0.0
+  ([df91d82](https://github.com/Xunnamius/workflow-playground/commit/df91d8298edd2d756f732b2245ba086e91197505))
diff --git a/changelog.config.js b/changelog.config.js
@@ -1,9 +1,25 @@
-// ? See: conventional-changelog/conventional-changelog-writer#options
+// ? See: conventional-changelog GitHub repository
 
+const semverValid = require('semver').valid;
 const sjx = require('shelljs');
-const EXCLUDE_SCOPES = ['reverts'];
 
-// ! These also have to be updated in build-test-deploy.yml
+// ? Commit types that will not be capitalized
+// ! Note: uses the post-angular-transform commit types
+const NO_CAPITALIZE_TYPES = ['Reverts'];
+
+// ? Commit types whose reversions are added to the changelog (releasers only!)
+// ! If you change this, you should also take a look at releaseRules in
+// ! release.config.js
+const SHOW_REVERSION_TYPES = ['feat', 'fix', 'perf', 'build'];
+
+const changelogTitle =
+  `# Changelog\n\n` +
+  `All notable changes to this project will be documented in this file.\n\n` +
+  `The format is based on [Conventional Commits](https://conventionalcommits.org),\n` +
+  `and this project adheres to [Semantic Versioning](https://semver.org).`;
+
+// ? Strings in commit messages that, when found, are skipped
+// ! These also have to be updated in build-test-deploy.yml when changed
 const SKIP_COMMANDS = '[skip ci], [ci skip], [skip github], [github skip]'.split(
   ', '
 );
@@ -20,11 +36,10 @@ if (wait.code != 0) throw new Error('failed to acquire angular transformation');
 const transform = Function(`"use strict";return (${wait.stdout})`)();
 const sentenceCase = (s) => s.charAt(0).toUpperCase() + s.slice(1);
 
-const changelogTitle =
-  `# Changelog\n\n` +
-  `All notable changes to this project will be documented in this file.\n\n` +
-  `The format is based on [Conventional Commits](https://conventionalcommits.org),\n` +
-  `and this project adheres to [Semantic Versioning](https://semver.org).`;
+// ? Releases made before this repo adopted semantic-release. They will be
+// ? collected together under a single header
+const legacyReleases = [];
+let shouldGenerate = true;
 
 module.exports = {
   changelogTitle,
@@ -36,17 +51,108 @@ module.exports = {
     warn: console.warn.bind(console)
   },
   writerOpts: {
+    generateOn: (commit) => {
+      const decision =
+        shouldGenerate === 'always' ||
+        (shouldGenerate && !!semverValid(commit.version));
+      shouldGenerate = true;
+      return decision;
+    },
     transform: (commit, context) => {
-      commit = transform(commit, context);
+      const version = commit.version || null;
+      const firstRelease =
+        version === context.gitSemverTags.slice(-1)[0].slice(1);
+
+      if (!firstRelease && version && !commit.type) {
+        // ? This commit does not have a type, but has a version. It must be a
+        // ? legacy release!
+        legacyReleases.push(commit);
+        commit = null;
+        shouldGenerate = false;
+      } else if (!firstRelease) {
+        commit = transform(commit, context);
+
+        if (commit) {
+          // ? Ignore any commits with commands like [skip ci] in them
+          if (SKIP_COMMANDS.some((cmd) => commit.subject.includes(cmd)))
+            return null;
+
+          if (!NO_CAPITALIZE_TYPES.some((type) => commit.type === type)) {
+            // ? Make the scope/subject upper case in the changelog (per my tastes)
+            commit.scope
+              ? (commit.scope = sentenceCase(commit.scope))
+              : (commit.subject = sentenceCase(commit.subject));
+          }
+
+          if (commit.type == 'Reverts') {
+            // ? Ignore reverts that didn't trigger releases
+            if (!SHOW_REVERSION_TYPES.includes(commit.subject)) return null;
+
+            commit.subject = `*${commit.subject}*`;
+          }
+
+          commit.notes.forEach((note) => {
+            note.text = sentenceCase(note.text.trim());
+
+            // ? If the text has a line break in it, make the first line bold and
+            // ? add a period before the line break unless there's a symbol
+            // ? already there
+            if (/\n/.test(note.text)) {
+              const [firstLine, ...remainder] = note.text.split('\n');
+              const addPeriod = !firstLine.endsWith('.');
+
+              note.text = `**${firstLine}${
+                addPeriod ? '.' : ''
+              }**\n${sentenceCase(remainder.join('\n'))}`;
+            }
+          });
+        }
+      }
+
+      // ? If this is the commit representing the earliest release (and there
+      // ? are legacy releases), use this commit to report collected legacy
+      // ? releases
+      if (firstRelease) {
+        shouldGenerate = 'always';
+
+        const getShortHash = (h) => h.substring(0, 7);
+        const shortHash = getShortHash(commit.hash);
+        const url = context.repository
+          ? `${context.host}/${context.owner}/${context.repository}`
+          : context.repoUrl;
 
-      // ? Make the scope/subject upper case in the changelog (per my tastes)
-      if (commit) {
-        if (SKIP_COMMANDS.some((cmd) => commit.subject.includes(cmd)))
-          return null;
+        const subject = legacyReleases
+          .reverse()
+          .map(({ hash, version }) => ({
+            url: `[${getShortHash(hash)}](${url}/commit/${hash})`,
+            version
+          }))
+          .reduce(
+            (subject, { url, version }) =>
+              `Version ${version} (${url})\n\n- ${subject}`,
+            `Version ${commit.version}`
+          );
 
-        commit.scope && !EXCLUDE_SCOPES.includes(commit.scope)
-          ? (commit.scope = sentenceCase(commit.scope))
-          : (commit.subject = sentenceCase(commit.subject));
+        commit = {
+          type: null,
+          scope: null,
+          subject,
+          id: null,
+          source: null,
+          merge: null,
+          header: null,
+          body: null,
+          footer: null,
+          notes: [],
+          references: [],
+          mentions: [],
+          revert: null,
+          hash: commit.hash,
+          shortHash,
+          gitTags: null,
+          committerDate: 'pre-CI/CD',
+          version: 'Archived Releases'
+        };
       }
 
       return commit;

diff --git a/release.config.js b/release.config.js
@@ -5,10 +5,8 @@ console.info(
   `SHOULD_UPDATE_CHANGELOG=${SHOULD_UPDATE_CHANGELOG} (${typeof SHOULD_UPDATE_CHANGELOG})`
 );
 
-const parserOpts = require('./changelog.config.js');
-const { changelogTitle, ...remainingOpts } = parserOpts;
-const { transform: _, ...caParserOpts } = remainingOpts;
-const { warn: __, ...rngParserOpts } = remainingOpts;
+const options = require('./changelog.config.js');
+const { changelogTitle, parserOpts, writerOpts } = options;
 
 module.exports = {
   //extends: '@xunnamius/semantic-release-config',
@@ -26,15 +24,19 @@ module.exports = {
       '@semantic-release/commit-analyzer',
       {
         preset: 'angular',
-        releaseRules: [{ type: 'build', release: 'patch' }],
-        parserOpts: caParserOpts
+        parserOpts,
+        // ! If you change releaseRules, you should also take a look at:
+        // !   - dependabot.yml
+        // !   - changelog.config.js
+        releaseRules: [{ type: 'build', release: 'patch' }]
       }
     ],
     [
       '@semantic-release/release-notes-generator',
       {
         preset: 'angular',
-        parserOpts: rngParserOpts
+        parserOpts,
+        writerOpts
       }
     ],
     ...(SHOULD_UPDATE_CHANGELOG === 'true'