Merge pull request #774 from corbob/dependency-resolution

(#773) Add new Chocolatey CLI dependency troubles page

input/en-us/choco/troubleshooting/dependency-troubles.md

@@ -0,0 +1,89 @@
+---
+Order: 10
+xref: choco-dependency-troubles
+Title: Dependency Troubleshooting in Chocolatey CLI
+Description: Troubleshooting steps for when you encounter issues related to dependencies.
+---
+
+## Installation and Upgrade Commands Fail for Many Seemingly Unrelated Packages
+
+Due to the way dependency resolution works, packages with dependencies can occasionally trigger undesirable behavior.
+When this happens, you will often be presented with both warnings and errors.
+The most important information will be in the errors, and not the warnings.
+
+When you encounter these errors, it is recommended to start with the package name mentioned in the error, and attempt to install it.
+Repeat this process with any other failing dependencies until they're all installed.
+
+### Example 1 - Upgrade All Fails to Upgrade One or More Packages
+
+This will sometimes be encountered with meta-packages, such as `obs-studio` which takes an exact-version dependency on `obs-studio.install`.
+When running `choco upgrade all` it will attempt to upgrade every installed package.
+Any packages which fail to install may be retried as part of a later dependency chain.
+For example, `obs-studio.install` may be upgraded, fail, and then later be tried again as part of the dependency chain for `obs-studio` itself.
+As a result, Chocolatey CLI's packages may be in an inconsistent state.
+This is typically characterized by a dependency resolution error message when performing package operations:
+
+```cmd
+Unable to resolve dependencies. 'obs-studio.install 29.0.2' is not compatible with 'obs-studio 29.1.1 constraint: obs-studio.install (>= 29.1.1)'.
+```
+
+This is normally resolved by upgrading the affected dependency.
+In this example, you would run `choco upgrade obs-studio.install` to resolve the issue.
+
+The following scenario illustrates what can happen during an `upgrade all` where a dependency fails to install.
+In this example, `obs-studio` installs, but `obs-studio.install` fails.
+Due to the dependency version range specified by `obs-studio`, the version of `obs-studio.install` that remains installed (due to the upgrade failure) does not satisfy the dependency requirement.
+
+To resolve the issue, we run `choco upgrade obs-studio.install` to get the correct dependency version installed.
+For packages that have a specific version dependency, add the `--version` option and specify the exact version to install.
+
+![Partial output from choco upgrade all, showing that obs-studio.install is attempted and failed](/assets/images/chocolatey/dependency-resolution-failure-1.png)
+![Continued output from choco upgrade all, showing that obs-studio metapackage is installed and subsequently re-attempts the upgrade to obs-studio.install which again fails, followed by a dependency resolution error in the next package and failing a seemingly unrelated package installation](/assets/images/chocolatey/dependency-resolution-failure-2.png)
+
+### Example 2 - Installing a Package Fails Due to Existing Missing Dependencies
+
+> :choco-warning: **WARNING**
+>
+> This example deals with multiple missing dependencies, and installs them while ignoring dependencies.
+> You will need to ensure you're installing the correct versions required for your dependencies.
+
+The following scenario illustrates what can happen during an `install` where multiple existing packages have dependencies that are not currently met.
+In this example, `glab` is attempting to be installed, but a number of `KB` packages are missing from the Chocolatey `lib` directory.
+
+1. We start by attempting to install `glab`, and note that
+
+  ![Output from choco install glab where it fails to resolve dependency 'KB306858'](/assets/images/chocolatey/kb-dependency-failure-1.png)
+
+2. To resolve the issue, we first run `choco install KB3063858` to install the first identified package.
+We note that this fails to install, so we make note of the package it couldn't find (`KB2919355`) and we run `choco install KB3063858 --ignore-dependencies` to ignore the dependency failure.
+
+  ![Output from choco install KB306858 where it fails to resolve dependency 'KB2919355'](/assets/images/chocolatey/kb-dependency-failure-2.png)
+
+3. Now that we have `KB3063858` installed, we attempt to run `choco install KB2919355` to install the next identified package.
+Again we make note of the next package (`KB2999226`) and install this package while ignoring dependencies: `choco install KB2919355 --ignore-dependencies`.
+
+  ![Output from choco install KB2919355 where it fails to resolve dependency 'KB2999226'](/assets/images/chocolatey/kb-dependency-failure-3.png)
+
+4. Now with `KB2919355` installed we continue with `choco install KB2999226`.
+Again we make note of the next package (`KB2919442`) and install this package while ignoring dependencies: `choco install KB2999226 --ignore-dependencies`.
+
+  ![Output from choco install KB2999226 where it fails to resolve dependency 'KB2919442'](/assets/images/chocolatey/kb-dependency-failure-4.png)
+
+5. Now with `KB2999226` installed, we attempt to run `choco install KB2919442`.
+We see that this one is actually already installed, so we attempt to install `glab` again.
+When `glab` fails to install, we make note of the next package missing in our chain: `chocolatey-windowsupdate.extension`.
+
+  ![Output from choco install KB2919442 where it is already installed. Following output is from choco install glab where it fails to resolve dependency 'chocolatey-windowsupdate.extension'](/assets/images/chocolatey/kb-dependency-failure-5.png)
+
+6. We install this in the same way as before (`choco install chocolatey-windowsupdate.extension`, then `choco install chocolatey-windowsupdate.extension --ignore-dependencies`).
+
+  ![Output from choco install chocolatey-windowsupdate.extension where it fails to resolve dependency 'KB3033929'](/assets/images/chocolatey/kb-dependency-failure-6.png)
+
+7. We install the next package (`KB3033929`) and note that it did not have any dependency failures.
+
+  ![Output from choco install KB3033929 where it installs with no dependency failures](/assets/images/chocolatey/kb-dependency-failure-7.png)
+
+8. So, we attempt our install of `glab` once more.
+Thankfully, we are able to install it with no dependency errors.
+
+  ![Output from choco install glab where it finally installs](/assets/images/chocolatey/kb-dependency-failure-8.png)

input/en-us/choco/troubleshooting/index.md

@@ -0,0 +1,6 @@
+---
+Order: 100
+xref: choco-troubleshooting
+Title: Chocolatey CLI Troubleshooting
+Description: Having issues running Chocolatey, check here for solutions
+---

input/en-us/troubleshooting.md

@@ -617,29 +617,4 @@ See the [TLS Best Practices documentation](https://learn.microsoft.com/en-us/dot
 
 ## `choco upgrade all` Fails to Upgrade a Package, Which Cascades into Failing Many More Seemingly Unrelated Packages
 
-Due to the way dependency resolution works, packages with certain dependency specifications can occasionally trigger undesirable behaviour when using `choco upgrade all` if the dependencies fail to install.
-Typically this will be encountered with meta-packages, such as `obs-studio` which takes a dependency on `obs-studio.install`.
-When running `choco upgrade all` it will attempt to upgrade every installed package. Any packages which fail to install may be retried as part of a later dependency chain.
-For example, `obs-studio.install` may be upgraded, fail, and then later be tried again as part of the dependency chain for `obs-studio` itself.
-As a result, Chocolatey CLI's packages may be in an inconsistent state.
-This is typically characterised by a dependency resolution error message when performing package operations:
-
-```cmd
-Unable to resolve dependencies. 'obs-studio.install 29.0.2' is not compatible with 'obs-studio 29.1.1 constraint: obs-studio.install (>= 29.1.1)'.
-```
-
-Typically this is resolvable by directly upgrading the affected dependency.
-This is normally resolved by upgrading the affected dependency.
-In this example, you would run `choco upgrade obs-studio.install` to resolve the issue.
-
-### Example
-
-The following scenario illustrates what can happen during an `upgrade all` where a dependency fails to install.
-In this example, `obs-studio` installs, but `obs-studio.install` fails.
-Due to the dependency version range specified by `obs-studio`, the version of `obs-studio.install` that remains installed (due to the upgrade failure) does not satisfy the dependency requirement.
-
-To resolve the issue, we run `choco upgrade obs-studio.install` to get the correct dependency version installed.
-For packages that have a specific version dependency, add the `--version` option and specify the exact version to install.
-
-![Partial output from choco upgrade all, showing that obs-studio.install is attempted and failed](/assets/images/chocolatey/dependency-resolution-failure-1.png)
-![Continued output from choco upgrade all, showing that obs-studio metapackage is installed and subsequently re-attempts the upgrade to obs-studio.install which again fails, followed by a dependency resolution error in the next package and failing a seemingly unrelated package installation](/assets/images/chocolatey/dependency-resolution-failure-2.png)
+See [the Chocolatey CLI Dependency Troubleshooting page](xref:choco-dependency-troubles)