Prioritize and write more about Helm schemas

Signed-off-by: Richard Wall <[email protected]>

Author: wallrj

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

@@ -7,15 +7,47 @@ cert-manager 1.16 includes various improvements to the metrics in the cert-manag
 
 ## Breaking changes
 
+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.
-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.
 
 ## 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,
@@ -107,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