docs: add migration guide

README.md

@@ -12,6 +12,7 @@ For version 4, please go to the [corresponding branch](https://github.com/nwutil
 - [Installation](https://github.com/nwutils/nw-builder#installation)
 - [Usage](https://github.com/nwutils/nw-builder#usage)
 - [API Reference](https://github.com/nwutils/nw-builder#api-reference)
+- [Migration Guide v3->v4](https://github.com/nwutils/nw-builder#migration)
 - [Contributing](https://github.com/nwutils/nw-builder#contributing)
 - [License](https://github.com/nwutils/nw-builder#license)
 
@@ -327,6 +328,209 @@ To get around it, run `ulimit -n 1024` (or add it to your `~/.bash_profile`). Fo
 
 This project was created by [Steffen Müller](https://github.com/steffenmllr) and has been maintained by [Gabe Paez](https://github.com/gabepaez), [Andy Trevorah](https://github.com/trevorah), [Adam Lynch](https://github.com/adam-lynch) and [Rémy Boulanouar](https://github.com/DblK) in the past. This project is currently maintained by [Ayushman Chhabra](https://github.com/ayushmxn).
 
+## Migration
+
+## Migration Guide (v3 -> v4)
+
+> We are working on making the migration process smoother. If you encounter any issues with the current guide, please open an issue or start a discussion.
+
+### Update `nw-builder`
+
+With npm:
+
+```shell
+npm update nw-builder@latest
+```
+
+With yarn:
+
+```shell
+yarn upgrade nw-builder@latest
+```
+
+With pnpm:
+
+```shell
+pnpm update nw-builder@latest
+```
+
+### Update options
+
+Let's take an example of v3 code and migrate it to v4.
+
+```javascript
+const NwBuilder = require("nw-builder");
+
+const nw = new NwBuilder({
+  files: ["./nwapp/**/*", "./other/**/*.js"],
+  version: "latest",
+  flavor: "normal",
+  platforms: ["win32", "win64", "osx32", "osx64", "linux32", "linux64"],
+  cacheDir: "./cache",
+  buildDir: "./build",
+  buildType: "versioned",
+  forceDownload: true,
+  appName: "nwdemo",
+  appVersion: "0.1.0",
+  argv: "--nw-stderr-logging",
+  macCredits: "./nwapp/credits.html",
+  macIcns: "./nwapp/mac.icns",
+  macPlist: { ... },
+  winVersionString: { ... },
+  winIco: "./nwapp/win.ico",
+  zip: true,
+  macZip: false,
+  mergeZip: false,
+});
+
+nw.build();
+```
+
+Update the import path
+
+```diff
+-const NwBuilder = require("nw-builder");
++const nwbuild = require("nw-builder");
+```
+
+Replace the `NwBuilder` initialization with a function
+
+```diff
+-const nw = new NwBuilder({
++await nwbuild({
+```
+
+The `files` property has been renamed to `srcDir`.
+
+```diff
+-  files: ["./nwapp/**/*", "./other/**/*.js"],
++  srcDir: "./nwapp/**/* ./other/**/*.js",
+```
+
+Add the `mode` option and remove the now redundant `nw.build` function call. The `build` call is made by `nwbuild` internally.
+
+```diff
++  mode: "build",
+
+-nw.build();
+```
+
+The `platforms` option has been removed and replaced with `platform` and `arch`. Notice that one `nwbuild` function call now creates one build for one platform and one arch only.
+
+```diff
+-  platforms: ["win32", "win64", "osx32", "osx64", "linux32", "linux64"],
++  platform: "linux", // "osx" for MacOS "win",  for Windows
++  arch: "x64", // "ia32" for 32 bit or "arm64" for arm based 65 bit architectures
+```
+
+The `buildDir` option has been rename to `outDir`.
+
+```diff
+-  buildDir: "./build",
++  outDir: "./build",
+```
+
+The `buildType` option has been removed.
+
+```diff
+-  buildType: "versioned",
+```
+
+The `forceDownload` option has been changed to `cache`.
+
+```diff
+-  forceDownload: true,
++  cache: false,
+```
+
+The `appName` option has been changed to `app.name`.
+
+```diff
+-  appName: "nwdemo",
++  app: { name: "nwdemo" },
+```
+
+The `appVersion` option has been changed to `app.version`.
+
+```diff
+-  appVersion: "0.1.0",
++  app: { version: "0.1.0" },
+```
+
+The `macCredit` option has been removed.
+
+```diff
+-  macCredits: "./nwapp/credits.html",
+```
+
+The `macIcns` option has been replaced with `icon`.
+
+```diff
+-  macIcns: "./nwapp/mac.icns",
++  icon: "./nwapp/mac.icns",
+```
+
+The `macPlist` option has been replaced by `app.*` options. Consult the [documentation](https://nwutils.io/nw-builder/mode-build.html#osxrc-object) for valid properties.
+
+```diff
+-  macPlist: { ... },
++  app: { ... },
+```
+
+The `winVersionString` option has been replaced with `app`. Consult the [documentation](https://nwutils.io/nw-builder/mode-build.html#winrc-object) for valid properties.
+
+```diff
+-  winVersionString: {
+-    'CompanyName': 'Some Company',
+-    'FileDescription': 'Process Name',
+-    'ProductName': 'Some Product',
+-    'LegalCopyright': 'Copyright 2017',
+-  }
++  app: {
++    company: "Some Company",
++    fileDescription: "Process Name",
++    productName: "Some Product",
++    legalCopyright: "Copyright (c) 2023",
++  }
+```
+
+The `winIco` option has been replaced by `app.icon`.
+
+```diff
+-  winIco: "./nwapp/win.ico",
++  app: { icon: "./nwapp/win.ico" },
+```
+
+The `macZip` option has been removed.
+
+```diff
+-  macZip: false,
+```
+
+The `mergeZip` option has been removed.
+
+```diff
+-  mergeZip: false,
+```
+
+The final code should look like this.
+
+```javascript
+const { nwbuild } = require("nw-builder");
+
+await nwbuild({
+  srcDir: "./nwapp/**/* ./other/**/*.js",
+  mode: "build",
+  version: "latest",
+  flavor: "normal",
+  platform: "linux",
+  arch: "x64",
+  outDir: "./build",
+  cache: false,
+  app: { ... },
+});
+```
+
 ## Contributing
 
 ### Getting Started