update doc to explain upgrade dependencies

package.json

@@ -17,9 +17,9 @@
   "scripts": {
     "eslint": "npx eslint . --ext=.js,.mjs,.cjs",
     "test": "npm run test --workspaces --if-present",
-    "monorepo:upgrade_versions": "node ./scripts/monorepo/upgrade_external_versions.mjs",
-    "monorepo:sync_packages_versions": "node ./scripts/monorepo/sync_packages_versions.mjs",
-    "monorepo:publish": "node ./scripts/monorepo/publish_packages.mjs",
+    "monorepo:upgrade_versions": "node ./scripts/upgrade_external_versions.mjs",
+    "monorepo:sync_packages_versions": "node ./scripts/sync_packages_versions.mjs",
+    "monorepo:publish": "node ./scripts/publish_packages.mjs",
     "playwright:install": "npx playwright install-deps && npx playwright install",
     "prettier": "prettier --write ."
   },

packages/monorepo/readme.md

@@ -2,9 +2,11 @@
 
 Helpers to manage multiple packages from a single repository. For example when using [NPM workspaces](https://docs.npmjs.com/cli/v8/using-npm/workspaces).
 
-## Updating a package
+This packages helps to perform 2 tasks that are a bit painful to do "by hand" inside a monorepo: "publish a new version" and "upgrade dependencies".
 
-Updating a package in a workspace by hand is time consuming and error prone. Let's see it with a basic example where a workspace contains two packages and you make a change to one of them.
+## Publish a new version
+
+Publishing a new version of a package in a monorepo by hand is time consuming and error prone. It's because you have to ensure packages versions are properly updated according to their inter-dependency. Let's see it with a basic example where a monorepo contains two packages and you make a change to one of them.
 
 _packages/main/package.json:_
 
@@ -51,7 +53,7 @@ At this point you are supposed to update "packages/main/package.json" like this:
 }
 ```
 
-In a workspace with many packages this is hard to do correctly and time consuming. You can automate the painful part as follows:
+In a monorepo with many packages this is hard to do correctly and time consuming. You can automate the painful part as follows:
 
 1. Run _syncPackagesVersions_
 2. Review changes with a tool like "git diff"
@@ -73,9 +75,9 @@ await syncPackagesVersions({
 
 Each package might need to increase their package.json "version" differently. When it's required _syncPackagesVersions_ increases PATCH number ("1.0.3" becomes "1.0.4"). After that it's up to you to review these changes to decide if you keep PATCH increment or want to increment MINOR or MAJOR instead.
 
-## publishPackages
+### publishPackages
 
-_publishPackages_ is an async function that will publish all packages in the workspace on NPM. But only the packages that are not already published.
+_publishPackages_ is an async function that will publish all packages in the monorepo on NPM. But only the packages that are not already published.
 
 ```js
 import { publishPackages } from "@jsenv/monorepo";
@@ -86,3 +88,91 @@ await publishPackages({
   directoryUrl: new URL("./", import.meta.url),
 });
 ```
+
+## Upgrade dependencies
+
+As a maintainer of a package with many dependencies you periodically want to check if there is new versions of your dependencies to stay up to date. We'll first see what NPM packages are usually doing and why it's a problem. Then we'll see how to avoid that problem. Finally we'll see how to use a function to upgrade dependencies because it can be a bit time consuming to do by hand.
+
+NPM introduced what usage of ^ or "\*" in your _package.json_.
+
+```json
+{
+  "dependencies": {
+    "foo": "^1.0.0"
+  }
+}
+```
+
+But it causes a problem.
+
+### The problem
+
+As a result "npm install" auto updates to latest versions if any is found. In the end any npm install can change the behaviour of your code if a new version was published since the last npm install.
+
+The sequence of events looks as below
+
+```console
+[7h00] npm install
+[7h01] npm downloads `[email protected]`
+[7h30] `[email protected]` is published on NPM
+[8h00] npm install
+[8h01] npm downloads `[email protected]`
+```
+
+Whenever you or someone else ends up with foo version `1.2.0` it can break the code or lead to different code behaviour. People will loose time trying to understand what's going on only to realize it comes from the new version.
+
+### But package-lock.json fixes that right?
+
+_package-lock.json_ fixes that but only if you run `npm ci`.
+And people are still used to start a project using `npm install + npm start`.
+
+The problem is that `npm install` does too many things.
+Most of the time you don't want to update your deps. The 2 most common scenarios are:
+
+- "I want want to install deps on a fresh project"
+- "I want to ensure my deps are in sync after git pull in a branch"
+
+"I want to update all my deps" happens from time to time but is usually not what you had in mind before executing "npm install"
+
+Moreover the usage of _package-lock.json_ remains optional.
+
+## How to avoid the problem
+
+Use explicit version in the package.json
+
+BAD
+
+```json
+{
+  "dependencies": {
+    "foo": "^1.0.0",
+    "bar": "2.*"
+  }
+}
+```
+
+GOOD
+
+```json
+{
+  "dependencies": {
+    "foo": "1.1.3",
+    "bar": "2.0.0"
+  }
+}
+```
+
+As a result there is no ambiguity on the version being used and we know the exact version in the glimpse of an eye.
+**You control when the version gets updated**
+
+Once versions are fixed you can update whenever you want by running "npm outdated" and decide what to update by hand.
+
+But inside large codebases with a lot of packages this process takes time, you can use the following function to perform "npm outdated" + update the versions in the package.json
+
+```js
+import { upgradeExternalVersions } from "@jsenv/monorepo";
+
+await upgradeExternalVersions({
+  directoryUrl: new URL("./", import.meta.url),
+});
+```

packages/monorepo/src/upgrade_external_versions.js

@@ -1,3 +1,14 @@
+/*
+ * Try to upgrade all packages that are external to a monorepo.
+ * - "external" means a package that is not part of the monorepo
+ * - "upgrade" means check if there is a more recent version on NPM registry
+ * and if yes, update the version in the package.json
+ *
+ * Versions declared in "dependencies", "devDependencies" and "peerDependencies" are updated
+ *
+ * Be sure to check ../readme.md#upgrade-dependencies
+ */
+
 import { UNICODE, createTaskLog } from "@jsenv/log";
 import { fetchLatestInRegistry } from "@jsenv/package-publish/src/internal/fetchLatestInRegistry.js";