Document automatic dependency downgrade option

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

content/master/concepts/packages.md

@@ -275,6 +275,32 @@ spec:
 # Removed for brevity
 ```
 
+#### Automatically update dependency versions
+
+Crossplane can automatically upgrade a package's dependency version to the minimum
+valid version that satisfies all the constraints. It is an alpha feature that
+requires enabling with the `--enable-dependency-version-upgrades` flag.
+
+There is also a configuration option to allow automatic downgrades of
+dependencies. Downgrading a package can cause unexpected behavior, therefore, this
+option is disabled by default. To enable it, you can set the
+`packageManager.enableAutomaticDependencyDowngrade=true`helm value. After enabling
+this option, the package manager will automatically downgrade a package's dependency
+version to the maximum valid version that satisfies the constraints.
+
+{{<hint "note" >}}
+This configuration requires the `--enable-dependency-version-upgrades` flag.
+{{</hint >}}
+
+{{<hint "important" >}}
+Enabling automatic dependency downgrades may have unintended consequences, such as:
+
+1) CRDs missing in the downgraded version, possibly leaving orphaned MRs without 
+controllers to reconcile them.
+2) Loss of data if downgraded CRD versions omit fields that were set before.
+3) Changes in the CRD storage version, which may prevent package version update.
+{{</hint >}}
+
 #### Ignore Crossplane version requirements
 
 A Configuration package may require a specific or minimum Crossplane version 

content/master/concepts/providers.md

@@ -302,6 +302,32 @@ spec:
 # Removed for brevity
 ```
 
+#### Automatically update dependency versions
+
+Crossplane can automatically upgrade a package's dependency version to the minimum
+valid version that satisfies all the constraints. It is an alpha feature that
+requires enabling with the `--enable-dependency-version-upgrades` flag.
+
+There is also a configuration option to allow automatic downgrades of
+dependencies. Downgrading a package can cause unexpected behavior, therefore, this
+option is disabled by default. To enable it, you can set the
+`packageManager.enableAutomaticDependencyDowngrade=true`helm value. After enabling
+this option, the package manager will automatically downgrade a package's dependency
+version to the maximum valid version that satisfies the constraints.
+
+{{<hint "note" >}}
+This configuration requires the `--enable-dependency-version-upgrades` flag.
+{{</hint >}}
+
+{{<hint "important" >}}
+Enabling automatic dependency downgrades may have unintended consequences, such as:
+
+1) CRDs missing in the downgraded version, possibly leaving orphaned MRs without 
+controllers to reconcile them.
+2) Loss of data if downgraded CRD versions omit fields that were set before.
+3) Changes in the CRD storage version, which may prevent package version update.
+{{</hint >}}
+
 #### Ignore Crossplane version requirements
 
 A Provider package may require a specific or minimum Crossplane version before