Merge pull request #1568 from wallrj/update-breaking-changes-details-1.16

Update breaking changes details 1.16

Author: cert-manager-prow[bot]

content/docs/releases/release-notes/release-notes-1.16.md

@@ -7,12 +7,47 @@ cert-manager 1.16 includes various improvements to the metrics in the cert-manag
 
 ## Breaking changes
 
-1. Venafi Issuer may fail to renew Certificates if the duration conflicts with the CA minimum / maximum duration policy in Venafi.
-2. Venafi Issuer may fail to renew Certificates if the issuer has been configured for TPP with username-password authentication.
-3. Helm schema validation may reject your existing Helm values files if they contain typos or unrecognized fields.
+1. Helm schema validation may reject your existing Helm values files if they contain typos or unrecognized fields.
+   For more details, refer to the [Helm](#helm) section below.
+1. Venafi Issuer may fail to renew certificates if the requested duration conflicts with the CA’s minimum or maximum policy settings in Venafi.
+   For more details, refer to the [Venafi Issuer](#venafi-issuer) section below.
+1. Venafi Issuer may fail to renew Certificates if the issuer has been configured for TPP with username-password authentication.
+   For more details, refer to the [Venafi Issuer](#venafi-issuer) section below.
 
 ## Themes
 
+### Helm
+
+The Helm chart now includes a JSON schema which will validate the values that you supply when installing the chart.
+This will help you to get your Helm values right first time.
+It will alert you to typos and unrecognized fields in your existing Helm values files.
+And it will make it easier for the cert-manager maintainers to maintain the Helm chart,
+avoiding typos and mistakes in the default values file.
+
+> ⚠️ Helm schema validation may reject your existing Helm values files if they contain typos or unrecognized fields.
+> You can use `helm template` to test your Helm values before you upgrade:
+> ```bash
+> helm template cert-manager \
+>   --repo https://charts.jetstack.io \
+>   --version [[VAR::cert_manager_latest_version]] \
+>   --values values.cert-manager.yaml
+> ```
+> Here's an example of an error that would be caught by the schema validation:
+> ```yaml
+> # values.cert-manager.yaml
+> global:
+>   logLevel: debug # ❗ Should be an integer.
+> ```
+> ```console
+> Error: values don't meet the specifications of the schema(s) in the following chart(s):
+> cert-manager:
+>  - global.logLevel: Invalid type. Expected: number, given: string
+> ```
+>
+> ℹ️ The schema files are generated by [helm-tool](https://github.com/cert-manager/helm-tool), a utility which generates Helm docs, schema files and performs linting.
+>
+> 📖 Read [Helm: Charts: Schema Files](https://helm.sh/docs/topics/charts/#schema-files) to learn more.
+
 ### Extended Metrics
 
 The webhook and cainjector components now have metrics servers,
@@ -104,14 +139,6 @@ And it reduces the peak memory use of the cert-manager components when they star
 because they no longer have to hold a duplicate unpaged list of resources in-memory
 while they add them to the client side cache.
 
-### Helm Schema Validation
-
-The Helm chart now includes a JSON schema which will validate the values that you supply when installing the chart.
-This will help you to get your Helm values right first time.
-It will alert you to typos and unrecognized fields in your existing Helm values files.
-And it will make it easier for the cert-manager maintainers to maintain the Helm chart,
-avoiding typos and mistakes in the default values file.
-
 ## Community
 
 Thanks again to all open-source contributors with commits in this release, including: TODO