Migration guide generation improvements (#5494)

* changelog/fragments/00-template.yaml: change migration body to multi-line YAML string * release/changelog: use 🎉 instead of 🎉 to ensure rendering of emoji * fixup existing migration guides Signed-off-by: Joe Lanford <joe.lanford@gmail.com>
operator-framework · Jan 14, 2022 · 43b5394 · 43b5394
1 parent d3b23b9
commit 43b5394
Show file tree

Hide file tree

Showing 7 changed files with 47 additions and 23 deletions.
diff --git a/changelog/fragments/00-template.yaml b/changelog/fragments/00-template.yaml
@@ -37,5 +37,9 @@ entries:
     # the migration guide. This is required for breaking changes.
     migration:
       header: Header text for the migration section
-      body: >
-        Body of the migration section.
+      body: |
+        Body of the migration section. This should be formatted as markdown and can
+        span multiple lines.
+
+        Using the YAML string '|' operator means that newlines in this string will
+        be honored and interpretted as newlines in the rendered markdown.
diff --git a/release/changelog/internal/migration_guide.go b/release/changelog/internal/migration_guide.go
@@ -33,7 +33,7 @@ weight: {{ .Weight }}
 {{ if .PullRequestLink }}
 _See {{ .PullRequestLink }} for more details._
 {{ end }}{{ else }}
-There are no migrations for this release! :tada:
+There are no migrations for this release! 🎉
 {{ end }}`
 
 var migrationGuideTmpl = template.Must(template.New("migrationGuide").Parse(migrationGuideTemplate))

diff --git a/release/changelog/internal/migration_guide_test.go b/release/changelog/internal/migration_guide_test.go
@@ -92,7 +92,7 @@ title: v999.999.999
 weight: 3
 ---
 
-There are no migrations for this release! :tada:
+There are no migrations for this release! 🎉
 `,
 		},
 	}

diff --git a/website/content/en/docs/upgrading-sdk-version/v1.12.0.md b/website/content/en/docs/upgrading-sdk-version/v1.12.0.md
@@ -3,4 +3,4 @@ title: v1.12.0
 weight: 998988000
 ---
 
-There are no migrations for this release! :tada:
+There are no migrations for this release! 🎉
diff --git a/website/content/en/docs/upgrading-sdk-version/v1.14.0.md b/website/content/en/docs/upgrading-sdk-version/v1.14.0.md
@@ -8,17 +8,29 @@ weight: 998986000
 Note that to ensure the backwards compatibility SDK tool will try to downgrade the versions used if you need to still scaffold the v1beta1 for CRDs and Webhooks to publish your solutions into older cluster versions. However, note that this version is no longer supported in Kubernetes 1.22+, `sigs.k8s.io/controller-runtime v0.10.0` or `controller-gen v0.7.0`.
 Following are the changes to be addressed in your `Makefile` and `go.mod` file if you are not using the `v1beta1` K8s APIs which are no longer supported from k8s `1.22` version.
 1) Update your `go.mod` file to upgrade the dependencies and run `go mod tidy` to download then
-```go 
-k8s.io/api v0.22.1 
-k8s.io/apimachinery v0.22.1 
-k8s.io/client-go v0.22.1 
-sigs.k8s.io/controller-runtime v0.10.0 
-2) Update your Makefile by - Replacing 
-- `ENVTEST_K8S_VERSION = 1.21` with `ENVTEST_K8S_VERSION = 1.22`
-- `$(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases` with `$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases` 
-- Now, you can also remove from the `Makefile` the `CRD_OPTIONS`, see below:
-``` # Produce CRDs that work back to Kubernetes 1.11 (no version conversion) CRD_OPTIONS ?= "crd:trivialVersions=true,preserveUnknownFields=false" ```
-3) Replace your `admissionReviewVersions={v1,v1beta1}` markers with `admissionReviewVersions=v1` 4) Run `make manifest` to re-generate your manifests with latest versions.
+   ```
+   k8s.io/api v0.22.1
+   k8s.io/apimachinery v0.22.1
+   k8s.io/client-go v0.22.1
+   sigs.k8s.io/controller-runtime v0.10.0
+   ```
+2) Update your Makefile by making the following replacements:
+   ```diff
+   - ENVTEST_K8S_VERSION = 1.21
+   + ENVTEST_K8S_VERSION = 1.22
+   ```
+   ```diff
+   - $(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+   + $(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+   ```
+
+3) Remove from the `Makefile` the `CRD_OPTIONS`, see below:
+   ```
+   # Produce CRDs that work back to Kubernetes 1.11 (no version conversion)
+   CRD_OPTIONS ?= "crd:trivialVersions=true,preserveUnknownFields=false"
+   ```
+4) Replace your `admissionReviewVersions={v1,v1beta1}` markers with `admissionReviewVersions=v1`
+5) Run `make manifest` to re-generate your manifests with latest versions.
 
 _See [#5228](https://github.com/operator-framework/operator-sdk/pull/5228) for more details._
 

diff --git a/website/content/en/docs/upgrading-sdk-version/v1.16.0.md b/website/content/en/docs/upgrading-sdk-version/v1.16.0.md
@@ -3,7 +3,7 @@ title: v1.16.0
 weight: 998984000
 ---
 
-## Header text for the migration section
+## Ansible-based operators: add resource limits
 
 Add into the `config/manager/manager.yaml` the following limits which are now scaffolded by default:
 ```yaml
@@ -14,7 +14,8 @@ Add into the `config/manager/manager.yaml` the following limits which are now sc
     memory: 768Mi
   requests:
     cpu: 10m
-    memory: 256Mi```
+    memory: 256Mi
+```
 **IMPORTANT:** Having resource limits is a best-practice and these values are reasonable defaults, but Operator authors should optimize these values based on their project's requirements.
 
 _See [#5274](https://github.com/operator-framework/operator-sdk/pull/5274) for more details._
@@ -28,11 +29,14 @@ _See [#5462](https://github.com/operator-framework/operator-sdk/pull/5462) for m
 ## Add annotation to specify the default container
 
 Add the following annotation into the file `config/manager/manager.yaml`
-```yaml ... template:
+```yaml
+...
+template:
   metadata:
     annotations:
       kubectl.kubernetes.io/default-container: manager
-... ```
+...
+```
 
 _See [#5330](https://github.com/operator-framework/operator-sdk/pull/5330) for more details._
 
@@ -46,9 +50,13 @@ _See [#5330](https://github.com/operator-framework/operator-sdk/pull/5330) for m
 
 Update the Makefile with the following changes. 
 1) Above `##@ Deployment` add the following:
-``` ... ifndef ignore-not-found
+```
+...
+ifndef ignore-not-found
   ignore-not-found = false
-endif ... ```
+endif
+...
+```
 2) Replace: ```sh kubectl delete -f - ``` With: ```sh kubectl delete --ignore-not-found=$(ignore-not-found) -f - ``` 
 
 **NOTE**  You can also compare your `Makefile` with the one tagged by this release, in `operator-sdk/testdata` of the [OperatorSDK](https://github.com/operator-framework/operator-sdk) project.

diff --git a/website/content/en/docs/upgrading-sdk-version/v1.8.0.md b/website/content/en/docs/upgrading-sdk-version/v1.8.0.md
@@ -3,4 +3,4 @@ title: v1.8.0
 weight: 998992000
 ---
 
-There are no migrations for this release! :tada:
+There are no migrations for this release! 🎉