docs: add migration steps

docs/releasenotes/0.23.md

@@ -4,7 +4,11 @@ https://github.com/actions-runner-controller/actions-runner-controller/milestone
 
 # BREAKING CHANGE : Workflow job webhooks require an explicit field set
 
-Previously the webhook workflow job was set as the default if no `githubEvent` was set:
+Previously the webhook event workflow job was set as the default if no `githubEvent` was set.
+
+**Migration Steps**
+
+Change this:
 
 ```yaml
   scaleUpTriggers:
@@ -12,7 +16,7 @@ Previously the webhook workflow job was set as the default if no `githubEvent` w
     duration: "30m"
 ```
 
-You now need to set `workflowJob: {}` explicitly
+To this:
 
 ```yaml
   scaleUpTriggers:
@@ -25,10 +29,51 @@ You now need to set `workflowJob: {}` explicitly
 
 Previously to use the pod `topologySpreadConstraint:` attribute in your runners you had to set `topologySpreadConstraints:` instead, this was a typo and has been corrected.
 
+**Migration Steps**
+
+Update your runners to use `topologySpreadConstraints:` instead
+
 # BREAKING CHANGE : Default sync period is now 1 minute instead of 10 minutes
 
 Since caching as been implemented the default sync period of 10 minutes is unnecessarily conservative and gives a poor out of the box user experience. If you need a 10 minute sync period ensure you explicitly set this value.
 
+**Migration Steps**
+
+Update your sync period, how this is done will depend on how you've deployed ARC.
 # BREAKING CHANGE : A metric is set by default
 
-Previously is no metric was provided and you were using pull based scaling, `TotalNumberOfQueuedAndInProgressWorkflowRuns` was applied. No default is set now and the end user must always set this metric explicitly if they want to use it.
+Previously if no metric was provided and you were using pull based scaling the `TotalNumberOfQueuedAndInProgressWorkflowRuns` was metric applied. No default is set now.
+
+**Migration Steps**
+
+Add in the `TotalNumberOfQueuedAndInProgressWorkflowRuns` metric where you are currenty relying on it
+
+```yaml
+
+apiVersion: actions.summerwind.dev/v1alpha1
+kind: RunnerDeployment
+metadata:
+  name: example-runner-deployment
+spec:
+  template:
+    spec:
+      organisation: my-awesome-organisation
+      labels:
+        - my-awesome-runner
+---
+apiVersion: actions.summerwind.dev/v1alpha1
+kind: HorizontalRunnerAutoscaler
+metadata:
+  name: example-runner-deployment-autoscaler
+spec:
+  scaleTargetRef:
+    name: example-runner-deployment
+  minReplicas: 1
+  maxReplicas: 5
+  metrics:
+  - type: TotalNumberOfQueuedAndInProgressWorkflowRuns
+    repositoryNames:
+    - owner/my-awesome-repo-1
+    - owner/my-awesome-repo-2
+    - owner/my-awesome-repo-3
+```