docs(migration guide): explain what to do about this.options in custo…

…m tasks

from a discussion on Slack https://financialtimes.slack.com/archives/C3TJ6KXEU/p1736527031572559

docs/migration-guides/v4.md

@@ -298,6 +298,79 @@ tasks:
 
 The keys in the `.toolkitrc.yml` are what determines the task name visible to Tool Kit, which was previously determined by the actual class name, so make sure they match.
 
+### 2.2.3. Custom tasks with options
+
+Your existing custom task may have been using `this.options` to reference options from your `.toolkitrc.yml`. Now that [we have separate plugin-wide and task-specific options](#12-move-options-to-optionsplugins), `this.options` in tasks refers to the task-specific options. You'll need to either change your task to reference `this.pluginOptions` to access the plugin-wide options, or move your `.toolkitrc.yml` options for your plugin to task-specific options. Which you choose depends on the use cases for your plugin's options:
+
+<table>
+<tr>
+<th></th><th>task-specific options</th><th>plugin-wide options</th>
+</tr>
+<tr><td>when to use</td>
+<td>options that could be different if the task could be reused for different use cases, e.g. a path to a config file</td>
+<td>options that would be the same for every task in a plugin no matter when they're being run, e.g. a system code</td>
+</tr>
+<tr><td>
+
+`.toolkitrc.yml`
+
+</td><td>
+
+```yml
+options:
+  tasks:
+    CustomTask:
+      config: 'path/to/config.js'
+
+commands:
+  build:local:
+    - CustomTask
+  build:ci:
+    - CustomTask:
+        config: 'path/to/ci-config.js'
+```
+
+</td><td>
+
+```yml
+options:
+  plugins:
+    './tool-kit/custom-plugin':
+      systemCode: 'next-article'
+```
+
+</td></tr><tr><td>
+
+your custom task
+
+</td><td>
+
+```js
+class CustomTask extends Task {
+  run() {
+    // { config: "path/to/config.js" },
+    // or, if run from `build:ci`,
+    // { config: "path/to/ci-config.js" }
+    this.options
+  }
+}
+```
+
+</td><td>
+
+```js
+class CustomTask extends Task {
+  run() {
+    // { systemCode: "next-article" }
+    this.pluginOptions
+  }
+}
+```
+
+</td></tr></table>
+
+It's possible to mix and match task-specific and plugin-wide options, so if you have some options that fall under one use case and some under the other, you should split the options up as appropriate.
+
 ### 2.3. Plugins with custom "placeholder" hooks
 
 If you're defining a "placeholder hook" so that you have a custom Tool Kit command you can run, **this is no longer required**; commands can be defined in your repo's `.toolkitrc.yml`. A placeholder hook will look something like this: