docs: further improvements for the 0.14 deprecation docs (#6823)

* docs: further improvements for the 0.14 deprecation docs * docs: fix deprecation guide reference docs links * docs: use h2 for deprecation context and h3 for each context item --------- Co-authored-by: Vladimir Vagaytsev <[email protected]>
garden-io · Feb 6, 2025 · 91b7fde · 91b7fde
1 parent 55e7308
commit 91b7fde
Show file tree

Hide file tree

Showing 11 changed files with 92 additions and 48 deletions.
diff --git a/core/src/docs/config.ts b/core/src/docs/config.ts
@@ -9,10 +9,10 @@
 import type Joi from "@hapi/joi"
 import { readFileSync } from "fs"
 import linewrap from "linewrap"
+import handlebars from "handlebars"
 import { resolve } from "path"
 import { projectSchema } from "../config/project.js"
 import { get, isFunction, isString } from "lodash-es"
-import handlebars from "handlebars"
 import type { JoiDescription } from "../config/common.js"
 import { STATIC_DIR } from "../constants.js"
 import type { BaseKeyDescription, NormalizeOptions } from "./common.js"
@@ -85,10 +85,11 @@ function makeMarkdownDescription(description: BaseKeyDescription, { showRequired
 
   const table = renderMarkdownTable(tableData)
 
-  let deprecatedDescription = "This field will be removed in a future release."
+  let deprecatedDescription: string | handlebars.SafeString = "This field will be removed in a future release."
 
   if (description.deprecated && isString(description.deprecationMessage)) {
-    deprecatedDescription = stripAnsi(description.deprecationMessage)
+    // we use SafeString so backticks are preserved in the final doc
+    deprecatedDescription = new handlebars.SafeString(stripAnsi(description.deprecationMessage))
   }
 
   return {

diff --git a/core/src/docs/generate.ts b/core/src/docs/generate.ts
@@ -207,7 +207,10 @@ export async function writeConfigReferenceDocs(
 async function updateDeprecationGuide(docsRoot: string, deprecationGuideFilename: string) {
   const guide = resolve(docsRoot, deprecationGuideFilename)
   const contents = (await readFile(guide)).toString()
-  const humanGenerated = contents.split("## Breaking changes")[0]
+
+  const marker = "<!-- DO NOT CHANGE BELOW - AUTO-GENERATED -->"
+
+  const humanGenerated = contents.split(marker)[0]
 
   // apply style for docs, using backticks instead of ansi codes
   const deprecations = getDeprecations((s) => `\`${s}\``)
@@ -220,12 +223,17 @@ async function updateDeprecationGuide(docsRoot: string, deprecationGuideFilename
   const breakingChanges: string[] = []
 
   for (const context of contexts) {
-    breakingChanges.push(`### ${context}`)
+    breakingChanges.push(`## ${context}`)
 
     const matchingDeprecations = Object.entries(deprecations).filter(([_, { contextDesc }]) => contextDesc === context)
-    for (const [id, { hint, featureDesc }] of matchingDeprecations) {
-      breakingChanges.push(`#### <a id="${id}">${featureDesc}</a>`)
+    for (const [id, { hint, featureDesc, hintReferenceLink }] of matchingDeprecations) {
+      breakingChanges.push(`<h3 id="${id}">${featureDesc}</h3>`)
       breakingChanges.push(hint)
+      if (hintReferenceLink) {
+        breakingChanges.push(
+          `For more information, please refer to the [${hintReferenceLink.name}](../${hintReferenceLink.link}).`
+        )
+      }
     }
   }
 
@@ -234,7 +242,8 @@ async function updateDeprecationGuide(docsRoot: string, deprecationGuideFilename
     dedent`
     ${humanGenerated.trimEnd()}
 
-    ## Breaking changes
+    ${marker}
+    <!-- This section is auto-generated by \`npm run generate-docs\`. Any changes above these comments will be preserved. Make changes to deprecations in \`deprecations.ts\`. -->
 
     ${breakingChanges.join("\n\n")}
     `

diff --git a/core/src/util/deprecations.ts b/core/src/util/deprecations.ts
@@ -18,29 +18,43 @@ export function getDeprecations(style: (s: string) => string = styles.highlight)
     containerDeploymentStrategy: {
       contextDesc: "Kubernetes provider configuration",
       featureDesc: `The ${style("deploymentStrategy")} config field`,
-      hint: `This field has no effect as the experimental support for blue/green deployments (via the ${style(`"blue-green"`)} strategy) has been removed.`,
+      hint: `Do not use this config field. It has no effect as the experimental support for blue/green deployments (via the ${style(`blue-green`)} strategy) has been removed.`,
+      hintReferenceLink: null,
     },
     dotIgnoreFiles: {
       contextDesc: "Project configuration",
       featureDesc: `The ${style("dotIgnoreFiles")} config field`,
       hint: `Use the ${style("dotIgnoreFile")} field instead. It only allows specifying one filename.`,
+      hintReferenceLink: {
+        name: `${style("dotIgnoreFile")} reference documentation`,
+        link: `reference/project-config.md#dotignorefile`,
+      },
     },
     apiVersionV0: {
       contextDesc: "Project configuration",
-      featureDesc: `${style(`apiVersion: ${GardenApiVersion.v0}`)} in the project config`,
+      featureDesc: `Using ${style(`apiVersion: ${GardenApiVersion.v0}`)} in the project config`,
       hint: dedent`
       Use ${style(`apiVersion: ${GardenApiVersion.v1}`)} or higher instead.
-    `,
+      `,
+      hintReferenceLink: {
+        name: `${style("apiVersion")} reference documentation`,
+        link: `reference/project-config.md#apiVersion`,
+      },
     },
     projectConfigModules: {
       contextDesc: "Project configuration",
-      featureDesc: `${style("modules")} config field`,
+      featureDesc: `The ${style("modules")} config field`,
       hint: `Please use the ${style("scan")} field instead.`,
+      hintReferenceLink: {
+        name: `${style("scan")} reference documentation`,
+        link: `reference/project-config.md#scan`,
+      },
     },
     kubernetesClusterInitCommand: {
       contextDesc: "Garden Commands",
-      featureDesc: `Kubernetes plugin command ${style("cluster-init")}`,
-      hint: "Do not use this command.",
+      featureDesc: `The Kubernetes plugin command ${style("cluster-init")}`,
+      hint: "Do not use this command. It has no effect.",
+      hintReferenceLink: null,
     },
   } as const
 }
@@ -49,22 +63,32 @@ export type Deprecation = keyof ReturnType<typeof getDeprecations>
 
 export const DOCS_DEPRECATION_GUIDE = `${DOCS_BASE_URL}/guides/deprecations`
 
-export function makeDeprecationMessage({ deprecation, styleLink }: { deprecation: Deprecation; styleLink?: boolean }) {
-  const { featureDesc, hint } = getDeprecations()[deprecation]
+export function makeDeprecationMessage({
+  deprecation,
+  includeLink,
+  style,
+}: {
+  deprecation: Deprecation
+  includeLink?: boolean
+  style?: boolean
+}) {
+  const { featureDesc, hint } = getDeprecations(style ? styles.highlight : (s) => `\`${s}\``)[deprecation]
 
   const lines = [`${featureDesc} is deprecated in 0.13 and will be removed in the next major release, Garden 0.14.`]
 
   if (hint) {
     lines.push(hint)
   }
 
-  let link = `${DOCS_DEPRECATION_GUIDE}#${deprecation}`
-  if (styleLink) {
-    link = styles.link(link)
+  if (includeLink) {
+    let link = `${DOCS_DEPRECATION_GUIDE}#${deprecation}`
+    if (style) {
+      link = styles.link(link)
+    }
+    lines.push(
+      `To make sure your configuration does not break when we release Garden 0.14, please follow the steps at ${link}`
+    )
   }
-  lines.push(
-    `To make sure your configuration does not break when we release Garden 0.14, please follow the steps at ${link}`
-  )
 
   return lines.join("\n")
 }
@@ -102,6 +126,6 @@ export function reportDeprecatedFeatureUsage({ apiVersion, log, deprecation }: D
     throw new FeatureNotAvailable({ apiVersion, deprecation })
   }
 
-  const warnMessage = makeDeprecationMessage({ deprecation, styleLink: true })
+  const warnMessage = makeDeprecationMessage({ deprecation, includeLink: true, style: true })
   emitNonRepeatableWarning(log, `\nDEPRECATION WARNING: ${warnMessage}\n`)
 }
diff --git a/docs/guides/deprecations.md b/docs/guides/deprecations.md
@@ -9,32 +9,45 @@ The next major version of Garden, 0.14, will contain breaking changes. To make t
 
 When using `apiVersion: garden.io/v1` in your project configuration file, Garden will warn you if your configuration depends on features that will be removed in Garden 0.14.
 
-**EXPERIMENTAL**: You can opt-in to the new behaviour in Garden 0.14 by using `apiVersion: garden.io/v2`. This setting will make Garden throw errors whenever it detects usage of deprecated functionality. Please note that as of today, not all warnings are in place, so we will still add new error conditions. Once the list of breaking changes is final, we will make this known here.
+**EXPERIMENTAL**: You can opt-in to the new behaviour in Garden 0.14 by using `apiVersion: garden.io/v2`. This setting will make Garden throw errors whenever it detects usage of deprecated functionality.
 
-## Breaking changes
+{% hint style="warning" %}
+Please note that as of today, not all warnings are in place, so we are still working on the list of breaking changes. Once the list of breaking changes is final, we will make this known here.
+{% endhint %}
 
-### Kubernetes provider configuration
+# Breaking changes
 
-#### <a id="containerDeploymentStrategy">The `deploymentStrategy` config field</a>
+<!-- DO NOT CHANGE BELOW - AUTO-GENERATED -->
+<!-- This section is auto-generated by `npm run generate-docs`. Any changes above these comments will be preserved. Make changes to deprecations in `deprecations.ts`. -->
 
-This field has no effect as the experimental support for blue/green deployments (via the `"blue-green"` strategy) has been removed.
+## Kubernetes provider configuration
 
-### Project configuration
+<h3 id="containerDeploymentStrategy">The `deploymentStrategy` config field</h3>
 
-#### <a id="dotIgnoreFiles">The `dotIgnoreFiles` config field</a>
+Do not use this config field. It has no effect as the experimental support for blue/green deployments (via the `blue-green` strategy) has been removed.
+
+## Project configuration
+
+<h3 id="dotIgnoreFiles">The `dotIgnoreFiles` config field</h3>
 
 Use the `dotIgnoreFile` field instead. It only allows specifying one filename.
 
-#### <a id="apiVersionV0">`apiVersion: garden.io/v0` in the project config</a>
+For more information, please refer to the [`dotIgnoreFile` reference documentation](../reference/project-config.md#dotignorefile).
+
+<h3 id="apiVersionV0">Using `apiVersion: garden.io/v0` in the project config</h3>
 
 Use `apiVersion: garden.io/v1` or higher instead.
 
-#### <a id="projectConfigModules">`modules` config field</a>
+For more information, please refer to the [`apiVersion` reference documentation](../reference/project-config.md#apiVersion).
+
+<h3 id="projectConfigModules">The `modules` config field</h3>
 
 Please use the `scan` field instead.
 
-### Garden Commands
+For more information, please refer to the [`scan` reference documentation](../reference/project-config.md#scan).
+
+## Garden Commands
 
-#### <a id="kubernetesClusterInitCommand">Kubernetes plugin command `cluster-init`</a>
+<h3 id="kubernetesClusterInitCommand">The Kubernetes plugin command `cluster-init`</h3>
 
-Do not use this command.
+Do not use this command. It has no effect.
diff --git a/docs/reference/action-types/Deploy/container.md b/docs/reference/action-types/Deploy/container.md
@@ -1001,7 +1001,7 @@ The maximum duration (in seconds) to wait for resources to deploy and become hea
 [spec](#spec) > limits
 
 {% hint style="warning" %}
-**Deprecated**: Please use the &#x60;cpu&#x60; and &#x60;memory&#x60; fields instead.
+**Deprecated**: Please use the `cpu` and `memory` fields instead.
 {% endhint %}
 
 Specify resource limits for the service.

diff --git a/docs/reference/module-types/container.md b/docs/reference/module-types/container.md
@@ -1895,7 +1895,7 @@ The maximum duration (in seconds) to wait for resources to deploy and become hea
 [services](#services) > limits
 
 {% hint style="warning" %}
-**Deprecated**: Please use the &#x60;cpu&#x60; and &#x60;memory&#x60; fields instead.
+**Deprecated**: Please use the `cpu` and `memory` fields instead.
 {% endhint %}
 
 Specify resource limits for the service.

diff --git a/docs/reference/module-types/jib-container.md b/docs/reference/module-types/jib-container.md
@@ -2110,7 +2110,7 @@ The maximum duration (in seconds) to wait for resources to deploy and become hea
 [services](#services) > limits
 
 {% hint style="warning" %}
-**Deprecated**: Please use the &#x60;cpu&#x60; and &#x60;memory&#x60; fields instead.
+**Deprecated**: Please use the `cpu` and `memory` fields instead.
 {% endhint %}
 
 Specify resource limits for the service.

diff --git a/docs/reference/project-config.md b/docs/reference/project-config.md
@@ -453,9 +453,8 @@ defaultEnvironment: "dev"
 ### `dotIgnoreFiles[]`
 
 {% hint style="warning" %}
-**Deprecated**: The dotIgnoreFiles config field is deprecated in 0.13 and will be removed in the next major release, Garden 0.14.
-Use the dotIgnoreFile field instead. It only allows specifying one filename.
-To make sure your configuration does not break when we release Garden 0.14, please follow the steps at https://docs.garden.io/guides/deprecations#dotIgnoreFiles
+**Deprecated**: The `dotIgnoreFiles` config field is deprecated in 0.13 and will be removed in the next major release, Garden 0.14.
+Use the `dotIgnoreFile` field instead. It only allows specifying one filename.
 {% endhint %}
 
 Specify a filename that should be used as ".ignore" file across the project, using the same syntax and semantics as `.gitignore` files. By default, patterns matched in `.gardenignore` files, found anywhere in the project, are ignored when scanning for actions and action sources.

diff --git a/docs/reference/providers/kubernetes.md b/docs/reference/providers/kubernetes.md
@@ -1280,9 +1280,8 @@ providers:
 {% endhint %}
 
 {% hint style="warning" %}
-**Deprecated**: The deploymentStrategy config field is deprecated in 0.13 and will be removed in the next major release, Garden 0.14.
-This field has no effect as the experimental support for blue/green deployments (via the &quot;blue-green&quot; strategy) has been removed.
-To make sure your configuration does not break when we release Garden 0.14, please follow the steps at https://docs.garden.io/guides/deprecations#containerDeploymentStrategy
+**Deprecated**: The `deploymentStrategy` config field is deprecated in 0.13 and will be removed in the next major release, Garden 0.14.
+Do not use this config field. It has no effect as the experimental support for blue/green deployments (via the `blue-green` strategy) has been removed.
 {% endhint %}
 
 Sets the deployment strategy for `container` deploy actions.

diff --git a/docs/reference/providers/local-kubernetes.md b/docs/reference/providers/local-kubernetes.md
@@ -1225,9 +1225,8 @@ providers:
 {% endhint %}
 
 {% hint style="warning" %}
-**Deprecated**: The deploymentStrategy config field is deprecated in 0.13 and will be removed in the next major release, Garden 0.14.
-This field has no effect as the experimental support for blue/green deployments (via the &quot;blue-green&quot; strategy) has been removed.
-To make sure your configuration does not break when we release Garden 0.14, please follow the steps at https://docs.garden.io/guides/deprecations#containerDeploymentStrategy
+**Deprecated**: The `deploymentStrategy` config field is deprecated in 0.13 and will be removed in the next major release, Garden 0.14.
+Do not use this config field. It has no effect as the experimental support for blue/green deployments (via the `blue-green` strategy) has been removed.
 {% endhint %}
 
 Sets the deployment strategy for `container` deploy actions.

diff --git a/docs/reference/workflow-config.md b/docs/reference/workflow-config.md
@@ -338,7 +338,7 @@ The maximum amount of RAM the workflow pod can use, in megabytes (i.e. 1024 = 1
 ### `limits`
 
 {% hint style="warning" %}
-**Deprecated**: Please use the &#x60;resources.limits&#x60; field instead.
+**Deprecated**: Please use the `resources.limits` field instead.
 {% endhint %}
 
 | Type     | Required |