@release-it/keep-a-changelog 2.2.2 → 2.5.0

package/.prettierrc

@@ -1,7 +1,7 @@
 {
-  "printWidth": 120,
   "singleQuote": true,
-  "proseWrap": "always",
-  "trailingComma": "none",
-  "arrowParens": "avoid"
+  "endOfLine": "lf",
+  "printWidth": 125,
+  "arrowParens": "avoid",
+  "trailingComma": "none"
 }

package/README.md

@@ -1,6 +1,6 @@
 # Keep-a-changelog plugin for release-it
 
-This [release-it plugin](https://github.com/release-it/release-it/blob/master/docs/plugins/README.md) maintains your
+This [release-it plugin](https://github.com/release-it/release-it/blob/master/docs/plugins.md) maintains your
 CHANGELOG.md file according to the [Keep A Changelog](https://keepachangelog.com/) standards.
 
 The idea and initial implementation comes [from @eMarek](https://github.com/release-it/release-it/issues/662).
@@ -21,10 +21,39 @@ In [release-it](https://github.com/release-it/release-it) config:
 
 ## Options
 
-| option         | default value  | description                                                                                                                                      |
-| -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| filename       | `CHANGELOG.md` | File with changelogs.                                                                                                                            |
-| strictLatest   | `true`         | Entry of latest version must be present in order to get correct changelog. Set this option to `false` if you expect latest version without logs. |
-| addUnreleased  | `false`        | It leaves "Unreleased" title row if set to `true`.                                                                                               |
-| keepUnreleased | `false`        | It leaves "Unreleased" title row unchanged if set to `true`.                                                                                     |
-| addVersionUrl  | `false`        | Links the version to the according changeset.                                                                                                    |
+| option            | default value    | description                                                                                                                                      |
+| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| filename          | `'CHANGELOG.md'` | File with changelogs.                                                                                                                            |
+| strictLatest      | `true`           | Entry of latest version must be present in order to get correct changelog. Set this option to `false` if you expect latest version without logs. |
+| addUnreleased     | `false`          | It leaves "Unreleased" title row if set to `true`.                                                                                               |
+| keepUnreleased    | `false`          | It leaves "Unreleased" title row unchanged if set to `true`.                                                                                     |
+| addVersionUrl     | `false`          | Links the version to the according changeset. Uses GitHub-compatible URLs by default, see other options to configure the URL format.             |
+| versionUrlFormats | See below.       | Determines the version URL format when `addVersionUrl` is set to `true`. Uses GitHub-compatible URLs by default.                                 |
+| head              | `'HEAD'`         | The git revision the new version tag is compared to in the Unreleased URL.                                                                       |
+
+### versionUrlFormats
+
+The URL formats used when `addVersionUrl` is set to `true`. Example configuration for a repository in Azure DevOps:
+
+```json
+"plugins": {
+  "@release-it/keep-a-changelog": {
+    "filename": "CHANGELOG.md",
+    "head": "main",
+    "addVersionUrl": true,
+    "versionUrlFormats": {
+      "repositoryUrl": "https://dev.azure.com/...",
+      "unreleasedUrl": "{repositoryUrl}/branchCompare?baseVersion=GT{tagName}&targetVersion=GB{head}",
+      "versionUrl": "{repositoryUrl}/branchCompare?baseVersion=GT{previousTag}&targetVersion=GT{tagName}",
+      "firstVersionUrl": "{repositoryUrl}?version=GT{tagName}"
+    }
+  }
+}
+```
+
+| option          | default value                                         | description                                                                                 |
+| --------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| repositoryUrl   | `'https://{host}/{repository}'`                       | The format of the repository URL.                                                           |
+| unreleasedUrl   | `'{repositoryUrl}/compare/{tagName}...{head}'`        | The format of the `[unreleased]` section URL.                                               |
+| versionUrl      | `'{repositoryUrl}/compare/{previousTag}...{tagName}'` | The format of a release version URL.                                                        |
+| firstVersionUrl | `'{repositoryUrl}/releases/tag/{tagName}'`            | The format of the first release version URL, i.e. when no previous tags have been released. |

package/index.js

@@ -2,6 +2,7 @@ const { Plugin } = require('release-it');
 const fs = require('fs');
 const path = require('path');
 const detectNewline = require('detect-newline');
+var format = require('string-template');
 
 const pad = num => ('0' + num).slice(-2);
 
@@ -10,16 +11,34 @@ const getFormattedDate = () => {
   return `${today.getFullYear()}-${pad(today.getMonth() + 1)}-${pad(today.getDate())}`;
 };
 
+/**
+ * Default formats used for creating version URLs. Uses GitHub URL formats, e.g.
+ *
+ * https://github.com/release-it/release-it/compare/1.0.0...HEAD
+ * https://github.com/release-it/release-it/compare/0.0.0...1.0.0
+ * https://github.com/release-it/release-it/releases/tag/1.0.0
+ */
+const defaultVersionUrlFormats = {
+  repositoryUrl: 'https://{host}/{repository}',
+  unreleasedUrl: '{repositoryUrl}/compare/{tagName}...{head}',
+  versionUrl: '{repositoryUrl}/compare/{previousTag}...{tagName}',
+  firstVersionUrl: '{repositoryUrl}/releases/tag/{tagName}'
+};
+
 class KeepAChangelog extends Plugin {
   async init() {
     await super.init();
-    const { filename, strictLatest, addUnreleased, keepUnreleased, addVersionUrl } = this.options;
+    const { filename, strictLatest, addUnreleased, keepUnreleased, addVersionUrl, versionUrlFormats, head } = this.options;
 
     this.filename = filename || 'CHANGELOG.md';
     this.strictLatest = strictLatest === undefined ? true : Boolean(strictLatest);
     this.addUnreleased = addUnreleased === undefined ? false : Boolean(addUnreleased);
     this.keepUnreleased = keepUnreleased === undefined ? false : Boolean(keepUnreleased);
     this.addVersionUrl = addVersionUrl === undefined ? false : Boolean(addVersionUrl);
+    this.versionUrlFormats = versionUrlFormats
+      ? { ...defaultVersionUrlFormats, ...versionUrlFormats }
+      : defaultVersionUrlFormats;
+    this.head = head || 'HEAD';
 
     this.changelogPath = path.resolve(this.filename);
     this.changelogContent = fs.readFileSync(this.changelogPath, 'utf-8');
@@ -34,15 +53,21 @@ class KeepAChangelog extends Plugin {
   }
 
   getChangelog(latestVersion) {
+    const { isIncrement } = this.config;
+    // Return the unchanged changelog content when no increment is made
+    if (!isIncrement) {
+      return this.changelogContent;
+    }
+
     const { changelog } = this.getContext();
     if (changelog) return changelog;
 
     const { filename, strictLatest } = this;
 
     const previousReleaseTitle = strictLatest ? `## [${latestVersion}]` : `## [`;
-    const hasPreviouReleaseSection = this.changelogContent.includes(previousReleaseTitle);
+    const hasPreviousReleaseSection = this.changelogContent.includes(previousReleaseTitle);
 
-    if (strictLatest && !hasPreviouReleaseSection) {
+    if (strictLatest && !hasPreviousReleaseSection) {
       throw Error(`Missing section for previous release ("${latestVersion}") in ${filename}.`);
     }
 
@@ -69,32 +94,40 @@ class KeepAChangelog extends Plugin {
     const { version, latestVersion, tagName, latestTag, repo } = this.config.getContext();
     let updatedChangelog = changelog;
 
-    const repositoryUrl = `https://${repo.host}/${repo.repository}`;
+    const repositoryUrl = format(this.versionUrlFormats.repositoryUrl, repo);
+    const unreleasedLinkRegex = new RegExp(`\\[unreleased\\]\\:.*${this.head}`, 'i');
 
     // Add or update the Unreleased link
-    const unreleasedUrl = `${repositoryUrl}/compare/${tagName}...HEAD`;
-    const unreleasedLink = `[Unreleased]: ${unreleasedUrl}`;
-    if (updatedChangelog.includes('[Unreleased]:')) {
-      updatedChangelog = updatedChangelog.replace(/\[Unreleased\]\:.*HEAD/, unreleasedLink);
+    const unreleasedUrl = format(this.versionUrlFormats.unreleasedUrl, { repositoryUrl, tagName, head: this.head });
+    const unreleasedLink = `[unreleased]: ${unreleasedUrl}`;
+    if (unreleasedLinkRegex.test(updatedChangelog)) {
+      updatedChangelog = updatedChangelog.replace(unreleasedLinkRegex, unreleasedLink);
     } else {
-      updatedChangelog = `${updatedChangelog}${this.EOL}${this.EOL}${unreleasedLink}`;
+      updatedChangelog = `${updatedChangelog}${this.EOL}${unreleasedLink}`;
+    }
+
+    // Add a link for the first tagged version
+    if (!latestTag) {
+      const firstVersionUrl = format(this.versionUrlFormats.firstVersionUrl, { repositoryUrl, tagName });
+      const firstVersionLink = `[${version}]: ${firstVersionUrl}`;
+      return `${updatedChangelog}${this.EOL}${firstVersionLink}`;
     }
 
     // Add a link for the new version
     const latestVersionLink = `[${latestVersion}]:`;
-    const releaseUrl = `${repositoryUrl}/compare/${latestTag}...${tagName}`;
-    const releaseLink = `[${version}]: ${releaseUrl}`;
+    const versionUrl = format(this.versionUrlFormats.versionUrl, { repositoryUrl, previousTag: latestTag, tagName });
+    const versionLink = `[${version}]: ${versionUrl}`;
     if (updatedChangelog.includes(latestVersionLink)) {
-      return updatedChangelog.replace(latestVersionLink, `${releaseLink}${this.EOL}${latestVersionLink}`);
+      return updatedChangelog.replace(latestVersionLink, `${versionLink}${this.EOL}${latestVersionLink}`);
     } else {
-      return `${updatedChangelog}${this.EOL}${releaseLink}`;
+      return `${updatedChangelog}${this.EOL}${versionLink}`;
     }
   }
 
   beforeRelease() {
     const { addUnreleased, keepUnreleased, addVersionUrl } = this;
-    const { isDryRun } = this.config;
-    if (isDryRun || keepUnreleased) return;
+    const { isDryRun, isIncrement } = this.config;
+    if (isDryRun || keepUnreleased || !isIncrement) return;
     const { version } = this.getContext();
     const formattedDate = getFormattedDate();
     const unreleasedTitle = addUnreleased ? this.unreleasedTitle + this.EOL + this.EOL : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@release-it/keep-a-changelog",
-  "version": "2.2.2",
+  "version": "2.5.0",
   "description": "Keep-a-changelog plugin for release-it",
   "main": "index.js",
   "scripts": {
@@ -29,16 +29,17 @@
     "url": "https://webpro.nl"
   },
   "dependencies": {
-    "detect-newline": "^3.1.0"
+    "detect-newline": "^3.1.0",
+    "string-template": "^1.0.0"
   },
   "devDependencies": {
     "bron": "^1.1.1",
-    "mock-fs": "^4.13.0",
-    "release-it": "^14.2.0",
-    "sinon": "^9.2.1"
+    "mock-fs": "^5.0.0",
+    "release-it": "^14.13.1",
+    "sinon": "^11.1.1"
   },
   "peerDependencies": {
-    "release-it": "^14.2.0"
+    "release-it": "^14.13.1"
   },
   "engines": {
     "node": ">=10"

package/test.js

@@ -22,10 +22,16 @@ mock({
     '\r\n\r\n## [Unreleased]\r\n\r\n* Item A\r\n* Item B\r\n\r\n## [1.0.0] - 2020-05-02\r\n\r\n* Item C\r\n* Item D',
   './CHANGELOG-UNRELEASED.md': '## [Unreleased]\n\n* Item A\n* Item B\n\n## [1.0.0] - 2020-05-02\n\n* Item C\n* Item D',
   './CHANGELOG-VERSION_URL.md':
-    '## [Unreleased]\n\n* Item A\n* Item B\n\n## [1.0.0] - 2020-05-02\n\n* Item C\n* Item D\n\n[Unreleased]: https://github.com/release-it/release-it/compare/1.0.0..HEAD\n[1.0.0]: https://github.com/release-it/release-it/compare/0.0.0...1.0.0',
+    '## [Unreleased]\n\n* Item A\n* Item B\n\n## [1.0.0] - 2020-05-02\n\n* Item C\n* Item D\n\n[unreleased]: https://github.com/release-it/release-it/compare/1.0.0..HEAD\n[1.0.0]: https://github.com/release-it/release-it/compare/0.0.0...1.0.0',
+  './CHANGELOG-VERSION_URL_FORMATS.md':
+    '## [Unreleased]\n\n* Item A\n* Item B\n\n## [1.0.0] - 2020-05-02\n\n* Item C\n* Item D\n\n[unreleased]: https://github.com/_git/release-it/release-it/compareBranch/1.0.0/HEAD\n[1.0.0]: https://github.com/_git/release-it/release-it/compareBranch/0.0.0/1.0.0',
+  './CHANGELOG-VERSION_URL_HEAD.md':
+    '## [Unreleased]\n\n* Item A\n* Item B\n\n## [1.0.0] - 2020-05-02\n\n* Item C\n* Item D\n\n[unreleased]: https://github.com/release-it/release-it/compare/1.0.0..main\n[1.0.0]: https://github.com/release-it/release-it/compare/0.0.0...1.0.0',
   './CHANGELOG-VERSION_URL_UNRELEASED.md':
+    '## [Unreleased]\n\n* Item A\n* Item B\n\n## [1.0.0] - 2020-05-02\n\n* Item C\n* Item D\n\n[unreleased]: https://github.com/user/project/compare/1.0.0..HEAD\n[1.0.0]: https://github.com/user/project/compare/0.0.0...1.0.0',
+  './CHANGELOG-VERSION_URL_UNRELEASED_TITLE_CASE.md':
     '## [Unreleased]\n\n* Item A\n* Item B\n\n## [1.0.0] - 2020-05-02\n\n* Item C\n* Item D\n\n[Unreleased]: https://github.com/user/project/compare/1.0.0..HEAD\n[1.0.0]: https://github.com/user/project/compare/0.0.0...1.0.0',
-  './CHANGELOG-VERSION_URL_NEW.md': '## [Unreleased]\n\n* Item A\n* Item B'
+  './CHANGELOG-VERSION_URL_NEW.md': '## [Unreleased]\n\n* Item A\n* Item B\n'
 });
 
 const readFile = file => fs.readFileSync(file).toString();
@@ -50,6 +56,13 @@ test('should throw for empty "unreleased" section', async t => {
   await assert.rejects(runTasks(plugin), /There are no entries under "Unreleased" section in CHANGELOG-EMPTY\.md/);
 });
 
+test('should not throw for empty "unreleased" section when no-increment flag is set', async t => {
+  const options = { increment: false, [namespace]: { filename: 'CHANGELOG-EMPTY.md' } };
+  const plugin = factory(Plugin, { namespace, options });
+  await runTasks(plugin);
+  assert.equal(plugin.getChangelog(), readFile('./CHANGELOG-EMPTY.md'));
+});
+
 test('should throw for missing section for previous release', async t => {
   const options = { [namespace]: { filename: 'CHANGELOG-MISSING.md' } };
   const plugin = factory(Plugin, { namespace, options });
@@ -142,7 +155,53 @@ test('should add links to the end of the file', async t => {
   assert.equal(plugin.getChangelog(), '* Item A\n* Item B');
   assert.match(
     readFile('./CHANGELOG-VERSION_URL.md'),
-    /^## \[1\.0\.1] - [0-9]{4}-[0-9]{2}-[0-9]{2}\n\n\* Item A\n\* Item B\n\n## \[1\.0\.0] - 2020-05-02\n\n\* Item C\n*\* Item D\n\n\[Unreleased]: https:\/\/github\.com\/release-it\/release-it\/compare\/1\.0\.1\.\.\.HEAD\n\[1\.0\.1]: https:\/\/github\.com\/release-it\/release-it\/compare\/1\.0\.0\.\.\.1\.0\.1\n\[1\.0\.0]: https:\/\/github\.com\/release-it\/release-it\/compare\/0\.0\.0\.\.\.1\.0\.0\n$/
+    /^## \[1\.0\.1] - [0-9]{4}-[0-9]{2}-[0-9]{2}\n\n\* Item A\n\* Item B\n\n## \[1\.0\.0] - 2020-05-02\n\n\* Item C\n*\* Item D\n\n\[unreleased]: https:\/\/github\.com\/release-it\/release-it\/compare\/1\.0\.1\.\.\.HEAD\n\[1\.0\.1]: https:\/\/github\.com\/release-it\/release-it\/compare\/1\.0\.0\.\.\.1\.0\.1\n\[1\.0\.0]: https:\/\/github\.com\/release-it\/release-it\/compare\/0\.0\.0\.\.\.1\.0\.0\n$/
+  );
+});
+
+test('should add links with custom URL formats to the end of the file', async t => {
+  const options = {
+    [namespace]: {
+      filename: 'CHANGELOG-VERSION_URL_FORMATS.md',
+      addVersionUrl: true,
+      versionUrlFormats: {
+        repositoryUrl: 'https://{host}/_git/{repository}',
+        unreleasedUrl: '{repositoryUrl}/compareBranch/{tagName}/{head}',
+        versionUrl: '{repositoryUrl}/compareBranch/{previousTag}/{tagName}'
+      }
+    }
+  };
+  const plugin = factory(Plugin, { namespace, options });
+  plugin.config.setContext({
+    latestTag: '1.0.0',
+    repo: {
+      host: 'github.com',
+      repository: 'release-it/release-it'
+    }
+  });
+  await runTasks(plugin);
+  assert.equal(plugin.getChangelog(), '* Item A\n* Item B');
+  assert.match(
+    readFile('./CHANGELOG-VERSION_URL_FORMATS.md'),
+    /^## \[1\.0\.1] - [0-9]{4}-[0-9]{2}-[0-9]{2}\n\n\* Item A\n\* Item B\n\n## \[1\.0\.0] - 2020-05-02\n\n\* Item C\n*\* Item D\n\n\[unreleased]: https:\/\/github\.com\/_git\/release-it\/release-it\/compareBranch\/1\.0\.1\/HEAD\n\[1\.0\.1]: https:\/\/github\.com\/_git\/release-it\/release-it\/compareBranch\/1\.0\.0\/1\.0\.1\n\[1\.0\.0]: https:\/\/github\.com\/_git\/release-it\/release-it\/compareBranch\/0\.0\.0\/1\.0\.0\n$/
+  );
+});
+
+test('should add links with custom head to the end of the file', async t => {
+  const options = { [namespace]: { filename: 'CHANGELOG-VERSION_URL_HEAD.md', addVersionUrl: true, head: 'main' } };
+  const plugin = factory(Plugin, { namespace, options });
+  plugin.config.setContext({
+    latestTag: '1.0.0',
+    repo: {
+      host: 'github.com',
+      repository: 'release-it/release-it'
+    }
+  });
+  await runTasks(plugin);
+  assert.equal(plugin.getChangelog(), '* Item A\n* Item B');
+  assert.match(
+    readFile('./CHANGELOG-VERSION_URL_HEAD.md'),
+    /^## \[1\.0\.1] - [0-9]{4}-[0-9]{2}-[0-9]{2}\n\n\* Item A\n\* Item B\n\n## \[1\.0\.0] - 2020-05-02\n\n\* Item C\n*\* Item D\n\n\[unreleased]: https:\/\/github\.com\/release-it\/release-it\/compare\/1\.0\.1\.\.\.main\n\[1\.0\.1]: https:\/\/github\.com\/release-it\/release-it\/compare\/1\.0\.0\.\.\.1\.0\.1\n\[1\.0\.0]: https:\/\/github\.com\/release-it\/release-it\/compare\/0\.0\.0\.\.\.1\.0\.0\n$/
   );
 });
 
@@ -162,17 +221,38 @@ test('should add unreleased section and links to the end of the file', async t =
   assert.equal(plugin.getChangelog(), '* Item A\n* Item B');
   assert.match(
     readFile('./CHANGELOG-VERSION_URL_UNRELEASED.md'),
-    /^## \[Unreleased]\n\n## \[1\.0\.1] - [0-9]{4}-[0-9]{2}-[0-9]{2}\n\n\* Item A\n\* Item B\n\n## \[1\.0\.0] - 2020-05-02\n\n\* Item C\n*\* Item D\n\n\[Unreleased]: https:\/\/github\.com\/user\/project\/compare\/1\.0\.1\.\.\.HEAD\n\[1\.0\.1]: https:\/\/github\.com\/user\/project\/compare\/1\.0\.0\.\.\.1\.0\.1\n\[1\.0\.0]: https:\/\/github\.com\/user\/project\/compare\/0\.0\.0\.\.\.1\.0\.0\n/
+    /^## \[Unreleased]\n\n## \[1\.0\.1] - [0-9]{4}-[0-9]{2}-[0-9]{2}\n\n\* Item A\n\* Item B\n\n## \[1\.0\.0] - 2020-05-02\n\n\* Item C\n*\* Item D\n\n\[unreleased]: https:\/\/github\.com\/user\/project\/compare\/1\.0\.1\.\.\.HEAD\n\[1\.0\.1]: https:\/\/github\.com\/user\/project\/compare\/1\.0\.0\.\.\.1\.0\.1\n\[1\.0\.0]: https:\/\/github\.com\/user\/project\/compare\/0\.0\.0\.\.\.1\.0\.0\n/
+  );
+});
+
+test('should match an existing unreleased link in title case', async t => {
+  const options = {
+    [namespace]: { filename: 'CHANGELOG-VERSION_URL_UNRELEASED_TITLE_CASE.md', addVersionUrl: true, addUnreleased: true }
+  };
+  const plugin = factory(Plugin, { namespace, options });
+  plugin.config.setContext({
+    latestTag: '1.0.0',
+    repo: {
+      host: 'github.com',
+      repository: 'user/project'
+    }
+  });
+  await runTasks(plugin);
+  assert.equal(plugin.getChangelog(), '* Item A\n* Item B');
+  assert.match(
+    readFile('./CHANGELOG-VERSION_URL_UNRELEASED_TITLE_CASE.md'),
+    /^## \[Unreleased]\n\n## \[1\.0\.1] - [0-9]{4}-[0-9]{2}-[0-9]{2}\n\n\* Item A\n\* Item B\n\n## \[1\.0\.0] - 2020-05-02\n\n\* Item C\n*\* Item D\n\n\[unreleased]: https:\/\/github\.com\/user\/project\/compare\/1\.0\.1\.\.\.HEAD\n\[1\.0\.1]: https:\/\/github\.com\/user\/project\/compare\/1\.0\.0\.\.\.1\.0\.1\n\[1\.0\.0]: https:\/\/github\.com\/user\/project\/compare\/0\.0\.0\.\.\.1\.0\.0\n/
   );
 });
 
-test('should add link to the end of a new changelog', async t => {
+test('should add links to the end of a new changelog', async t => {
   const options = {
     [namespace]: { filename: 'CHANGELOG-VERSION_URL_NEW.md', addVersionUrl: true, strictLatest: false }
   };
   const plugin = factory(Plugin, { namespace, options });
   sinon.stub(plugin, 'getLatestVersion').returns('0.0.0');
   plugin.config.setContext({
+    latestTag: undefined,
     increment: 'major',
     repo: {
       host: 'github.com',
@@ -183,6 +263,6 @@ test('should add link to the end of a new changelog', async t => {
   assert.equal(plugin.getChangelog(), '* Item A\n* Item B');
   assert.match(
     readFile('./CHANGELOG-VERSION_URL_NEW.md'),
-    /^## \[1\.0\.0] - [0-9]{4}-[0-9]{2}-[0-9]{2}\n\n\* Item A\n\* Item B\n\n\[Unreleased]: https:\/\/github\.com\/user\/project\/compare\/1\.0\.0\.\.\.HEAD\n\[1.0.0]: https:\/\/github\.com\/user\/project\/compare\/0\.0\.0\.\.\.1\.0\.0\n$/
+    /^## \[1\.0\.0] - [0-9]{4}-[0-9]{2}-[0-9]{2}\n\n\* Item A\n\* Item B\n\n\[unreleased]: https:\/\/github\.com\/user\/project\/compare\/1\.0\.0\.\.\.HEAD\n\[1.0.0]: https:\/\/github\.com\/user\/project\/releases\/tag\/1\.0\.0\n$/
   );
 });