chore: add migration notes from v5 to master branch

docs/migration-v5-to-v6.md

@@ -0,0 +1,76 @@
+# Migration guide from Verdaccio 5 to Verdaccio 6
+
+Notes regarding breaking changes for next major release.
+
+> This list might growth over the development.
+
+## Breaking changes
+
+### New node-api interface [#2165](https://github.com/verdaccio/verdaccio/pull/2165)
+
+If you are using the node-api, the new structure is Promise based and less arguments.
+
+```js
+import { runServer } from '@verdaccio/node-api';
+// or
+import { runServer } from 'verdaccio';
+const app = await runServer(); // default configuration
+const app = await runServer('./config/config.yaml');
+const app = await runServer({ configuration });
+app.listen(4000, (event) => {
+  // do something
+});
+```
+
+### allow other password hashing algorithms [#1917](https://github.com/verdaccio/verdaccio/pull/1917)
+
+The current implementation of the `htpasswd` module supports multiple hash formats on verify, but only `crypt` on sign in.
+`crypt` is an insecure old format, so to improve the security of the new `verdaccio` release we introduce the support of multiple hash algorithms on sign in step.
+
+#### New hashing algorithms
+
+The new possible hash algorithms to use are `bcrypt`, `md5`, `sha1`. `bcrypt` is chosen as a default, because of its customizable complexity and overall reliability. You can read more about them [here](https://httpd.apache.org/docs/2.4/misc/password_encryptions.html).
+
+Two new properties are added to `auth` section in the configuration file:
+
+- `algorithm` to choose the way you want to hash passwords.
+- `rounds` is used to determine `bcrypt` complexity. So one can improve security according to increasing computational power.
+
+Example of the new `auth` config file section:
+
+```yaml
+auth:
+htpasswd:
+  file: ./htpasswd
+  max_users: 1000
+  # Hash algorithm, possible options are: "bcrypt", "md5", "sha1", "crypt".
+  algorithm: bcrypt
+  # Rounds number for "bcrypt", will be ignored for other algorithms.
+  rounds: 10
+```
+
+### Refactor config module, experiments renamed to flags [#1996](https://github.com/verdaccio/verdaccio/pull/1996)
+
+- The `experiments` configuration is renamed to `flags`. The functionality is exactly the same.
+
+```js
+flags: token: false;
+search: false;
+```
+
+- The `self_path` property from the config file is being removed in favor of `config_file` full path.
+- Refactor `config` module, better types and utilities
+
+### legacy token signature by removing crypto.createDecipher is deprecated [#1953](https://github.com/verdaccio/verdaccio/pull/1953)
+
+- Replace signature handler for legacy tokens by removing deprecated crypto.createDecipher by createCipheriv
+- **The new signature invalidates all previous tokens generated by Verdaccio 5 or previous versions**.
+- The secret key must have 32 characters long
+  > Remediation, update `.verdaccio-db.json` secret field with a secret key with 32 characters.
+
+#### New environment variables
+
+Introduce environment variables for legacy tokens.
+
+- `VERDACCIO_LEGACY_ALGORITHM`: Allows to define the specific algorithm for the token signature which by default is `aes-256-ctr`
+- `VERDACCIO_LEGACY_ENCRYPTION_KEY`: By default, the token stores in the database, but using this variable allows to get it from memory