Update adapters to use Release Script v3 (#978)

CHANGELOG.md

@@ -6,8 +6,9 @@
 	(at the beginning of a new line )
 -->
 ## __WORK IN PROGRESS__
-* (AlCalzone) Enable Dependabot by default, update Node.js version references (#977) · [Migration guide](docs/updates/20220925_update_node_version.md)
 * (mcm1957) Fix: use `adapter.` instead of `this.` in `main.js` in legacy mode (#972)
+* (AlCalzone) Enable Dependabot by default, update Node.js version references (#977) · [Migration guide](docs/updates/20220925_update_node_version.md)
+* (AlCalzone) Update the release script to version 3 (#978) · [Migration guide](docs/updates/20220925_releasescript_v3.md)
 
 ## 2.2.1 (2022-09-08)
 * (AlCalzone) Fix `lint` command for JS adapters · [Migration guide](docs/updates/20220908_fix_lint_command.md)

docs/updates/20220925_releasescript_v3.md

@@ -0,0 +1,38 @@
+# Update Release Script to v3
+
+Version 3 of the release script is much more powerful, but also requires a few changes to your adapter:
+
+**Install the latest version and additional plugins:**
+
+```bash
+npm i -D @alcalzone/release-script@latest @alcalzone/release-script-plugin-iobroker@latest @alcalzone/release-script-plugin-license@latest @alcalzone/release-script-plugin-manual-review@latest
+```
+
+**Configure the release script to use the new plugins:**
+
+Add a new file `.releaseconfig.json` with the following contents:
+
+```json
+{
+	"plugins": ["iobroker", "license", "manual-review"]
+}
+```
+
+These plugins will do the following:
+
+-   Update io-package.json, including translating the news
+-   Check the license to make sure it contains an up to date year
+-   Ask you to review the automatically done changes before publishing
+
+If your adapter uses TypeScript or React or something else that needs a build step, you can instruct the release script to execute this before committing the changes:
+
+```json
+{
+	"plugins": ["iobroker", "license", "manual-review"],
+	"exec": {
+		"before_commit": "npm run build"
+	}
+}
+```
+
+For more details on the changes, see https://github.com/AlCalzone/release-script

templates/_releaseconfig.json.ts

@@ -0,0 +1,26 @@
+import type { TemplateFunction } from "../src/lib/createAdapter";
+
+const templateFunction: TemplateFunction = answers => {
+	const useReleaseScript = answers.releaseScript === "yes";
+	if (!useReleaseScript) return;
+
+	const useTypeScript = answers.language === "TypeScript";
+	const useAdminReact = answers.adminUi === "react";
+	const useTabReact = answers.tabReact === "yes";
+	const useReact = useAdminReact || useTabReact;
+
+	const template: Record<string, any> = {
+		plugins: ["iobroker", "license", "manual-review"],
+	};
+	if (useTypeScript || useReact) {
+		template.exec = {
+			before_commit: "npm run build",
+		}
+	}
+
+
+	return JSON.stringify(template, undefined, '\t');
+};
+
+templateFunction.customPath = ".releaseconfig.json";
+export = templateFunction;

templates/index.ts

@@ -24,6 +24,7 @@ const templates: { name: string, templateFunction: TemplateFunction }[] = [
 	{ name: "_gitignore.ts", templateFunction: require("./_gitignore") },
 	{ name: "_prettierignore.ts", templateFunction: require("./_prettierignore") },
 	{ name: "_prettierrc.js.ts", templateFunction: require("./_prettierrc.js") },
+	{ name: "_releaseconfig.json.ts", templateFunction: require("./_releaseconfig.json") },
 	{ name: "_vscode/extensions.json.ts", templateFunction: require("./_vscode/extensions.json") },
 	{ name: "_vscode/settings.json.ts", templateFunction: require("./_vscode/settings.json") },
 	{ name: "admin/_eslintrc_js_react.json.ts", templateFunction: require("./admin/_eslintrc_js_react.json") },

templates/package.json.ts

@@ -103,7 +103,12 @@ const templateFunction: TemplateFunction = async answers => {
 			"prettier",
 		] : []),
 		...(useNyc ? ["nyc"] : []),
-		...(useReleaseScript ? ["@alcalzone/release-script@2"] : [])
+		...(useReleaseScript ? [
+			"@alcalzone/release-script",
+			"@alcalzone/release-script-plugin-iobroker",
+			"@alcalzone/release-script-plugin-license",
+			"@alcalzone/release-script-plugin-manual-review"
+		] : [])
 	]
 		.sort()
 		.map((dep) => (async () => `"${getPackageName(dep)}": "${await fetchPackageReferenceVersion(dep)}"`))

test/baselines/ReleaseScript_JS/.releaseconfig.json

@@ -0,0 +1,7 @@
+{
+	"plugins": [
+		"iobroker",
+		"license",
+		"manual-review"
+	]
+}

test/baselines/ReleaseScript_JS/README.md

@@ -0,0 +1,137 @@
+![Logo](admin/test-adapter.png)
+# ioBroker.test-adapter
+
+[![NPM version](https://img.shields.io/npm/v/iobroker.test-adapter.svg)](https://www.npmjs.com/package/iobroker.test-adapter)
+[![Downloads](https://img.shields.io/npm/dm/iobroker.test-adapter.svg)](https://www.npmjs.com/package/iobroker.test-adapter)
+![Number of Installations](https://iobroker.live/badges/test-adapter-installed.svg)
+![Current version in stable repository](https://iobroker.live/badges/test-adapter-stable.svg)
+
+[![NPM](https://nodei.co/npm/iobroker.test-adapter.png?downloads=true)](https://nodei.co/npm/iobroker.test-adapter/)
+
+**Tests:** ![Test and Release](https://github.com/AlCalzone/ioBroker.test-adapter/workflows/Test%20and%20Release/badge.svg)
+
+## test-adapter adapter for ioBroker
+
+Describe your project here
+
+## Developer manual
+This section is intended for the developer. It can be deleted later.
+
+### DISCLAIMER
+
+Please make sure that you consider copyrights and trademarks when you use names or logos of a company and add a disclaimer to your README.
+You can check other adapters for examples or ask in the developer community. Using a name or logo of a company without permission may cause legal problems for you.
+
+### Getting started
+
+You are almost done, only a few steps left:
+1. Create a new repository on GitHub with the name `ioBroker.test-adapter`
+1. Initialize the current folder as a new git repository:  
+	```bash
+	git init -b main
+	git add .
+	git commit -m "Initial commit"
+	```
+1. Link your local repository with the one on GitHub:  
+	```bash
+	git remote add origin https://github.com/AlCalzone/ioBroker.test-adapter
+	```
+
+1. Push all files to the GitHub repo:  
+	```bash
+	git push origin main
+	```
+1. Add a new secret under https://github.com/AlCalzone/ioBroker.test-adapter/settings/secrets. It must be named `AUTO_MERGE_TOKEN` and contain a personal access token with push access to the repository, e.g. yours. You can create a new token under https://github.com/settings/tokens.
+
+1. Head over to [main.js](main.js) and start programming!
+
+### Best Practices
+We've collected some [best practices](https://github.com/ioBroker/ioBroker.repositories#development-and-coding-best-practices) regarding ioBroker development and coding in general. If you're new to ioBroker or Node.js, you should
+check them out. If you're already experienced, you should also take a look at them - you might learn something new :)
+
+### Scripts in `package.json`
+Several npm scripts are predefined for your convenience. You can run them using `npm run <scriptname>`
+| Script name | Description |
+|-------------|-------------|
+| `test:js` | Executes the tests you defined in `*.test.js` files. |
+| `test:package` | Ensures your `package.json` and `io-package.json` are valid. |
+| `test:integration` | Tests the adapter startup with an actual instance of ioBroker. |
+| `test` | Performs a minimal test run on package files and your tests. |
+| `lint` | Runs `ESLint` to check your code for formatting errors and potential bugs. |
+| `translate` | Translates texts in your adapter to all required languages, see [`@iobroker/adapter-dev`](https://github.com/ioBroker/adapter-dev#manage-translations) for more details. |
+| `release` | Creates a new release, see [`@alcalzone/release-script`](https://github.com/AlCalzone/release-script#usage) for more details. |
+
+### Writing tests
+When done right, testing code is invaluable, because it gives you the 
+confidence to change your code while knowing exactly if and when 
+something breaks. A good read on the topic of test-driven development 
+is https://hackernoon.com/introduction-to-test-driven-development-tdd-61a13bc92d92. 
+Although writing tests before the code might seem strange at first, but it has very 
+clear upsides.
+
+The template provides you with basic tests for the adapter startup and package files.
+It is recommended that you add your own tests into the mix.
+
+### Publishing the adapter
+Using GitHub Actions, you can enable automatic releases on npm whenever you push a new git tag that matches the form 
+`v<major>.<minor>.<patch>`. We **strongly recommend** that you do. The necessary steps are described in `.github/workflows/test-and-release.yml`.
+
+Since you installed the release script, you can create a new
+release simply by calling:
+```bash
+npm run release
+```
+Additional command line options for the release script are explained in the
+[release-script documentation](https://github.com/AlCalzone/release-script#command-line).
+
+To get your adapter released in ioBroker, please refer to the documentation 
+of [ioBroker.repositories](https://github.com/ioBroker/ioBroker.repositories#requirements-for-adapter-to-get-added-to-the-latest-repository).
+
+### Test the adapter manually on a local ioBroker installation
+In order to install the adapter locally without publishing, the following steps are recommended:
+1. Create a tarball from your dev directory:  
+	```bash
+	npm pack
+	```
+1. Upload the resulting file to your ioBroker host
+1. Install it locally (The paths are different on Windows):
+	```bash
+	cd /opt/iobroker
+	npm i /path/to/tarball.tgz
+	```
+
+For later updates, the above procedure is not necessary. Just do the following:
+1. Overwrite the changed files in the adapter directory (`/opt/iobroker/node_modules/iobroker.test-adapter`)
+1. Execute `iobroker upload test-adapter` on the ioBroker host
+
+## Changelog
+<!--
+	Placeholder for the next version (at the beginning of the line):
+	### **WORK IN PROGRESS**
+-->
+
+### **WORK IN PROGRESS**
+* (Al Calzone) initial release
+
+## License
+MIT License
+
+Copyright (c) 2022 Al Calzone <[email protected]>
+
+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.

test/baselines/ReleaseScript_JS/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "iobroker.test-adapter",
+  "version": "0.0.1",
+  "description": "test-adapter",
+  "author": {
+    "name": "Al Calzone",
+    "email": "[email protected]"
+  },
+  "homepage": "https://github.com/AlCalzone/ioBroker.test-adapter",
+  "license": "MIT",
+  "keywords": [
+    "ioBroker",
+    "template",
+    "Smart Home",
+    "home automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AlCalzone/ioBroker.test-adapter.git"
+  },
+  "dependencies": {
+    "@iobroker/adapter-core": "^2.6.6"
+  },
+  "devDependencies": {
+    "@alcalzone/release-script": "^3.5.9",
+    "@alcalzone/release-script-plugin-iobroker": "^3.5.9",
+    "@alcalzone/release-script-plugin-license": "^3.5.9",
+    "@alcalzone/release-script-plugin-manual-review": "^3.5.9",
+    "@iobroker/adapter-dev": "^1.1.0",
+    "@iobroker/testing": "^4.1.0",
+    "chai": "^4.3.6",
+    "chai-as-promised": "^7.1.1",
+    "eslint": "^8.24.0",
+    "mocha": "^9.2.2",
+    "proxyquire": "^2.1.3",
+    "sinon-chai": "^3.7.0",
+    "sinon": "^13.0.2"
+  },
+  "main": "main.js",
+  "files": [
+    "admin{,/!(src)/**}/!(tsconfig|tsconfig.*|.eslintrc).json",
+    "admin{,/!(src)/**}/*.{html,css,png,svg,jpg,js}",
+    "lib/",
+    "www/",
+    "io-package.json",
+    "LICENSE",
+    "main.js"
+  ],
+  "scripts": {
+    "test:js": "mocha --config test/mocharc.custom.json \"{!(node_modules|test)/**/*.test.js,*.test.js,test/**/test!(PackageFiles|Startup).js}\"",
+    "test:package": "mocha test/package --exit",
+    "test:integration": "mocha test/integration --exit",
+    "test": "npm run test:js && npm run test:package",
+    "lint": "eslint .",
+    "translate": "translate-adapter",
+    "release": "release-script"
+  },
+  "bugs": {
+    "url": "https://github.com/AlCalzone/ioBroker.test-adapter/issues"
+  },
+  "readmeFilename": "README.md"
+}

test/baselines/ReleaseScript_TS/.releaseconfig.json

@@ -0,0 +1,10 @@
+{
+	"plugins": [
+		"iobroker",
+		"license",
+		"manual-review"
+	],
+	"exec": {
+		"before_commit": "npm run build"
+	}
+}

test/baselines/releaseScript/package.json → test/baselines/ReleaseScript_TS/package.json

@@ -25,7 +25,10 @@
     "@iobroker/adapter-core": "^2.6.6"
   },
   "devDependencies": {
-    "@alcalzone/release-script": "^2.2.2",
+    "@alcalzone/release-script": "^3.5.9",
+    "@alcalzone/release-script-plugin-iobroker": "^3.5.9",
+    "@alcalzone/release-script-plugin-license": "^3.5.9",
+    "@alcalzone/release-script-plugin-manual-review": "^3.5.9",
     "@iobroker/adapter-dev": "^1.1.0",
     "@iobroker/testing": "^4.1.0",
     "@tsconfig/node14": "^1.0.3",

test/create-adapter.test.ts

@@ -583,17 +583,35 @@ describe("adapter creation =>", () => {
 				);
 			});
 
-			it("Release Script", async () => {
+			it("Release Script (JS)", async () => {
 				const answers: Answers = {
 					...baseAnswers,
 					releaseScript: "yes",
+					language: "JavaScript",
+				};
+				await expectSuccess(
+					"ReleaseScript_JS",
+					answers,
+					(file) =>
+						file.name === "package.json" ||
+						file.name === "README.md" ||
+						file.name === ".releaseconfig.json",
+				);
+			});
+
+			it("Release Script (TS)", async () => {
+				const answers: Answers = {
+					...baseAnswers,
+					releaseScript: "yes",
+					language: "TypeScript",
 				};
 				await expectSuccess(
-					"releaseScript",
+					"ReleaseScript_TS",
 					answers,
 					(file) =>
 						file.name === "package.json" ||
-						file.name === "README.md",
+						file.name === "README.md" ||
+						file.name === ".releaseconfig.json",
 				);
 			});