From e9461789531df561165ea2ca90a00d6fe9a0f9b6 Mon Sep 17 00:00:00 2001
From: Paulo Castro <paulo@balena.io>
Date: Tue, 8 Mar 2022 17:59:19 +0000
Subject: [PATCH] Include link to Wiki release notes in version update
 notifications

Change-type: patch
---
 lib/utils/update.ts        | 41 +++++++++++++++-----
 tests/utils/update.spec.ts | 79 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 110 insertions(+), 10 deletions(-)
 create mode 100644 tests/utils/update.spec.ts

diff --git a/lib/utils/update.ts b/lib/utils/update.ts
index 3daad369..d81c0692 100644
--- a/lib/utils/update.ts
+++ b/lib/utils/update.ts
@@ -1,5 +1,5 @@
 /*
-Copyright 2016-2019 Balena
+Copyright 2016-2022 Balena
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -40,14 +40,35 @@ export function notify() {
 		}
 	}
 	const up = notifier.update;
-	if (
-		up &&
-		(require('semver') as typeof import('semver')).lt(up.current, up.latest)
-	) {
-		notifier.notify({
-			defer: false,
-			message: `Update available ${up.current} → ${up.latest}\n
-https://github.com/balena-io/balena-cli/blob/master/INSTALL.md`,
-		});
+	const message = up && getNotifierMessage(up);
+	if (message) {
+		notifier.notify({ defer: false, message });
 	}
 }
+
+export function getNotifierMessage(updateInfo: UpdateNotifier.UpdateInfo) {
+	const semver = require('semver') as typeof import('semver');
+	const message: string[] = [];
+	const [current, latest] = [updateInfo.current, updateInfo.latest];
+
+	if (semver.lt(current, latest)) {
+		message.push(
+			`Update available ${current} → ${latest}`,
+			'https://github.com/balena-io/balena-cli/blob/master/INSTALL.md',
+		);
+		const currentMajor = semver.major(current);
+		const latestMajor = semver.major(latest);
+		if (currentMajor !== latestMajor) {
+			message.push(
+				'',
+				`Check the v${latestMajor} release notes at:`,
+				getReleaseNotesUrl(latestMajor),
+			);
+		}
+	}
+	return message.join('\n');
+}
+
+function getReleaseNotesUrl(majorVersion: number) {
+	return `https://github.com/balena-io/balena-cli/wiki/CLI-v${majorVersion}-Release-Notes`;
+}
diff --git a/tests/utils/update.spec.ts b/tests/utils/update.spec.ts
new file mode 100644
index 00000000..c726b3b3
--- /dev/null
+++ b/tests/utils/update.spec.ts
@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2022 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { expect } from 'chai';
+import * as stripIndent from 'common-tags/lib/stripIndent';
+
+import { getNotifierMessage } from '../../build/utils/update';
+
+import type { UpdateInfo } from 'update-notifier';
+
+describe('getNotifierMessage() unit test', function () {
+	const template: UpdateInfo = {
+		current: '',
+		latest: '',
+		type: 'latest',
+		name: '',
+	};
+
+	it('should return a simple update message including installation instructions', () => {
+		const mockUpdateInfo = {
+			...template,
+			current: '12.1.1',
+			latest: '12.3.0',
+		};
+		const msg = getNotifierMessage(mockUpdateInfo);
+		expect(msg).to.equal(stripIndent`
+			Update available 12.1.1 → 12.3.0
+			https://github.com/balena-io/balena-cli/blob/master/INSTALL.md`);
+	});
+
+	it('should include a release notes link when a new major version is available', () => {
+		const mockUpdateInfo = {
+			...template,
+			current: '12.1.1',
+			latest: '13.3.0',
+		};
+		const msg = getNotifierMessage(mockUpdateInfo);
+		expect(msg).to.equal(stripIndent`
+			Update available 12.1.1 → 13.3.0
+			https://github.com/balena-io/balena-cli/blob/master/INSTALL.md
+
+			Check the v13 release notes at:
+			https://github.com/balena-io/balena-cli/wiki/CLI-v13-Release-Notes`);
+	});
+
+	it('should return an empty string if no updates are available', () => {
+		const mockUpdateInfo = {
+			...template,
+			current: '12.1.1',
+			latest: '12.1.1',
+		};
+		const msg = getNotifierMessage(mockUpdateInfo);
+		expect(msg).to.equal('');
+	});
+
+	it('should return an empty string if no updates are available', () => {
+		const mockUpdateInfo = {
+			...template,
+			current: '14.1.1',
+			latest: '12.1.1',
+		};
+		const msg = getNotifierMessage(mockUpdateInfo);
+		expect(msg).to.equal('');
+	});
+});