[PM] Enhance single version requirements imposed during bootstrapping (…

…opensearch-project#5675)

Add `--single-version` switch to `bootstrap` to manipulate the behavior of single-version validation

Signed-off-by: Miki <[email protected]>

CHANGELOG.md

@@ -29,6 +29,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - [Discover] Display inner properties in the left navigation bar [#5429](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5429)
 - [Discover] Added customizable pagination options based on Discover UI settings [#5610](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5610)
 - [Chrome] Introduce registerCollapsibleNavHeader to allow plugins to customize the rendering of nav menu header ([#5244](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5244))
+- [PM] Enhance single version requirements imposed during bootstrapping ([#5675](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5675))
 - [Custom Branding] Relative URL should be allowed for logos ([#5572](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5572))
 - [Discover] Enhanced the data source selector with added sorting functionality ([#5609](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/5609))
 - [Multiple Datasource] Add datasource picker component and use it in devtools and tutorial page when multiple datasource is enabled ([#5756](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5756))

packages/osd-pm/README.md

@@ -141,6 +141,40 @@ yarn osd
 Bootstrapping also calls the `osd:bootstrap` script for every included project.
 This is intended for packages that need to be built/transpiled to be usable.
 
+#### Single-version validation
+
+Bootstrapping, by default, applies a `strict` single-version validation where it requires all the dependencies defined
+more than once to have the same version-range in the `package.json` files of Dashboards, packages, and plugins. If a
+violation is identified, bootstrapping terminates with an error. This behavior can be controlled using the 
+`--single-version` switch. Using any switch other than the default can result in the installation of versions of the
+dependencies that were never tested and this could lead to unexpected results.
+
+```
+yarn osd bootstrap --single-version=loose
+```
+In `loose` mode, bootstrapping reconciles the various versions installed as a result of having multiple ranges for a 
+dependency, by choosing one that satisfies all said ranges. Even though installing the chosen version updates the 
+`yarn.lock` files, no `package.json` changes would be needed.
+
+```
+yarn osd bootstrap --single-version=force
+```
+In `force` mode, bootstrapping acts like `loose` for each dependency. If despite that, a suitable version was not found,
+it switches to behave like the `brute-force` mode (see below).
+
+```
+yarn osd bootstrap --single-version=brute-force
+```
+In `brute-force` mode, bootstrapping chooses the newest of the various versions installed, irrespective of whether it 
+satisfies any of the ranges. Installing the chosen version, bootstrapping updates the `yarn.lock` files and applies a 
+range, in the form of `^<version>`, to all `package.json` files that declared the dependency.
+
+```
+yarn osd bootstrap --single-version=ignore
+```
+In `ignore` mode, bootstrapping behaves very similar to the `strict` mode by showing errors when different ranges of a 
+package are marked as dependencies, but without terminating.
+
 ### Running scripts
 
 Some times you want to run the same script across multiple packages and plugins,