Repository: kedro-org/kedro
Pull request: [Ready] 0.19 Migration guide documentation
## Description
Closes #3500 

I've created a page in `resources/migration.html` to store a narrative version of the migration guide we have previously published in release notes. I suggest that we use it for future releases and just have a section in the release notes that points to it in the future. It's better for SEO to have it in docs and I think more people will think to look in docs than the release notes (but if anyone disagrees, we can still put some notes in the release docs and point through to a tidier and more complete version in docs).

## Development notes
Added a page and some revised notes. Needs engineering input to add example code and confirm the files in a user project that would be affected.


## Developer Certificate of Origin
We need all contributions to comply with the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). All commits must be signed off by including a `Signed-off-by` line in the commit message. [See our wiki for guidance](https://github.com/kedro-org/kedro/wiki/Guidelines-for-contributing-developers/).

If your PR is blocked due to unsigned commits, then you must follow the instructions under "Rebase the branch" on the GitHub Checks page for your PR. This will retroactively add the sign-off to all unsigned commits and allow the DCO check to pass.

## Checklist

- [ ] Read the [contributing](https://github.com/kedro-org/kedro/blob/main/CONTRIBUTING.md) guidelines
- [ ] Signed off each commit with a [Developer Certificate of Origin (DCO)](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository)
- [ ] Opened this PR as a 'Draft Pull Request' if it is work-in-progress
- [ ] Updated the documentation to reflect the code changes
- [ ] Added a description of this change in the [`RELEASE.md`](https://github.com/kedro-org/kedro/blob/main/RELEASE.md) file
- [ ] Added tests to cover my changes
- [ ] Checked if this change will affect Kedro-Viz, and if so, communicated that with the Viz team


Problem statement:
Create migration guide documentation content
## Description
Beyond the content in the release notes (or to replace it) there needs to be a page to point at that explains migration tasks for each breaking release. This should be relatively straightforward in 0.19 as we've a release note but it needs some structuring and extra narrative flow.

The reason I think we need this over and above the release notes is that not everyone uses the release notes or searches there for guidance. If they get an error as a result of using an older project with 0.19, it's likely they may first search our docs or google for an answer than head automatically to the release notes (they may not realise/understand that their error is a result of a Kedro version upgrade). So including the content in the docs is sensible (and we can decide later if we are introducing redundancy by adding similar content, or if in future we link to the docs in the release notes, and always document migration in the docs).

Hints from issue discussion:
See the PR https://github.com/kedro-org/kedro/pull/3544 for a first draft of a page of migration narrative for 0.19. It needs some time from engineering to flesh out the example snippets and explain where those changes should be applied. I've guided this through comments (which need to be removed). Handing over to engineering for this task. Thanks!

Commit message: Add link to migration guide to release notes

Signed-off-by: Jo Stichbury <jo_stichbury@mckinsey.com>

Patch to review:
diff --git a/RELEASE.md b/RELEASE.md
index 3bcf6773d8..2ab73e229e 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -30,11 +30,18 @@
 * Added documentation about `bootstrap_project` and `configure_project`.
 * Added documentation about `kedro run` and hook execution order.
 
+## Migration guide from Kedro 0.18.* to 0.19.*
+[See the migration guide for 0.19 in the Kedro documentation](https://docs.kedro.org/en/latest/resources/migration.html).
+
 # Release 0.19.1
 
 ## Bug fixes and other changes
 * Loosened pin for `kedro-telemtry` to fix dependency issues in `0.19.0`.
 
+## Migration guide from Kedro 0.18.* to 0.19.*
+[See the migration guide for 0.19 in the Kedro documentation](https://docs.kedro.org/en/latest/resources/migration.html).
+
+
 # Release 0.19.0
 
 ## Major features and improvements
@@ -98,26 +105,8 @@
 * The starters `pandas-iris`, `pyspark-iris`, `pyspark`, and `standalone-datacatalog` have been archived.
 
 ## Migration guide from Kedro 0.18.* to 0.19.*
-* Removed the custom Kedro syntax for `--params`, use the OmegaConf syntax instead by replacing `:` with `=`.
-* Removed the `create_default_data_set()` method in the `Runner`. To overwrite the default dataset creation, use the new `Runner` class argument `extra_dataset_patterns` instead.
-* Removed `project_version` in `pyproject.toml` please use `kedro_init_version` instead.
-
-### Datasets
-* If you use `APIDataSet`, move all `requests` specific arguments (e.g. `params`, `headers`), except for `url` and `method`, to under `load_args`.
-* Using the `layer` attribute at the top level is removed. Please move `layer` inside the `metadata` -> `kedro-viz` attributes.
-* Renamed dataset and error classes, in accordance with the [Kedro lexicon](https://github.com/kedro-org/kedro/wiki/Kedro-documentation-style-guide#kedro-lexicon). Dataset classes ending with "DataSet" and error classes starting with "DataSet" are removed. Note that all of the below classes are also importable from `kedro.io`; only the module where they are defined is listed as the location.
+[See the migration guide for 0.19 in the Kedro documentation](https://docs.kedro.org/en/latest/resources/migration.html).
 
-| Type                        | Removed Alias               | Location                       |
-| --------------------------- | --------------------------- | ------------------------------ |
-| `AbstractDataset`           | `AbstractDataSet`           | `kedro.io.core`                |
-| `AbstractVersionedDataset`  | `AbstractVersionedDataSet`  | `kedro.io.core`                |
-| `CachedDataset`             | `CachedDataSet`             | `kedro.io.cached_dataset`      |
-| `LambdaDataset`             | `LambdaDataSet`             | `kedro.io.lambda_dataset`      |
-| `MemoryDataset`             | `MemoryDataSet`             | `kedro.io.memory_dataset`      |
-| `DatasetError`              | `DataSetError`              | `kedro.io.core`                |
-| `DatasetAlreadyExistsError` | `DataSetAlreadyExistsError` | `kedro.io.core`                |
-| `DatasetNotFoundError`      | `DataSetNotFoundError`      | `kedro.io.core`                |
-* All other dataset classes are removed from the core Kedro repository (`kedro.extras.datasets`). Install and import them from the [`kedro-datasets`](https://github.com/kedro-org/kedro-plugins/tree/main/kedro-datasets) package instead.
 
 ### Logging
 `logging.yml` is now independent of Kedro's run environment and only used if `KEDRO_LOGGING_CONFIG` is set to point to it.
diff --git a/docs/source/resources/index.md b/docs/source/resources/index.md
index ce24876a0a..6dc1858901 100644
--- a/docs/source/resources/index.md
+++ b/docs/source/resources/index.md
@@ -5,5 +5,6 @@
 
 ../faq/faq
 glossary
+migration
 
 ```
diff --git a/docs/source/resources/migration.md b/docs/source/resources/migration.md
new file mode 100644
index 0000000000..ed69434841
--- /dev/null
+++ b/docs/source/resources/migration.md
@@ -0,0 +1,123 @@
+# Migration guide
+
+[See the release notes on GitHub](https://github.com/kedro-org/kedro/releases/) for comprehensive information about the content of each Kedro release.
+
+
+## Migrate an existing project that uses Kedro 0.18.* to use 0.19.*
+
+### Custom syntax for `--params` was removed
+[Kedro 0.19.0](https://github.com/kedro-org/kedro/releases/tag/0.19.0) removed the custom Kedro syntax for `--params`. To update, you need to use the OmegaConf syntax instead by replacing `:` with `=`.
+
+If you previously used this command to pass parameters to `kedro run`:
+
+```bash
+kedro run --params=param_key1:value1,param_key2:2.0
+```
+You should now use the following:
+
+```bash
+kedro run --params=param_key1=value1,param_key2=2.0
+```
+
+For more information see ["How to specify parameters at runtime"](https://docs.kedro.org/en/stable/configuration/parameters.html#how-to-specify-parameters-at-runtime).
+
+### `create_default_data_set()` was removed from `Runner`
+Kedro 0.19 removed the `create_default_data_set()` method in the `Runner`. To overwrite the default dataset creation, you need to use the new `Runner` class argument `extra_dataset_patterns` instead.
+
+On class instantiation, pass the `extra_dataset_patterns` argument, and overwrite the default `MemoryDataset` creation as follows:
+
+```python
+from kedro.runner import ThreadRunner
+
+runner = ThreadRunner(extra_dataset_patterns={"{default}": {"type": "MyCustomDataset"}})
+```
+
+### `project_version` was removed
+Kedro 0.19 removed `project_version` in `pyproject.toml`. Use `kedro_init_version` instead:
+
+```diff
+[tool.kedro]
+package_name = "my_project"
+project_name = "my project"
+- project_version = "0.19.1"
++ kedro_init_version = "0.19.1"
+```
+
+### Datasets changes in 0.19
+
+#### `requests`-specific arguments in `catalog.yml` have moved
+From 0.19, if you use `APIDataset`, you need to move all `requests`-specific arguments, e.g. `params`, `headers`, in the hierarchy to sit under `load_args`. The `url` and `method` arguments are not affected.
+
+For example the following `APIDataset` in `catalog.yml` changes from the following in 0.18.x code:
+
+```yaml
+us_corn_yield_data:
+  type: api.APIDataSet
+  url: https://quickstats.nass.usda.gov
+  credentials: usda_credentials
+  params:
+    key: SOME_TOKEN
+    format: JSON
+```
+
+to this in 0.19.x:
+
+```yaml
+us_corn_yield_data:
+  type: api.APIDataSet
+  url: https://quickstats.nass.usda.gov
+  credentials: usda_credentials
+  load_args:
+    params:
+      key: SOME_TOKEN
+      format: JSON
+```
+
+#### The `layer` attribute in `catalog.yml` has moved
+From 0.19, the `layer` attribute at the top level has been  moved inside the `metadata` -> `kedro-viz` attribute. You need to update `catalog.yml` accordingly.
+
+The following `catalog.yml` entry changes from the following in 0.18.x code:
+
+```yaml
+companies:
+  type: pandas.CSVDataSet
+  filepath: data/01_raw/companies.csv
+  layer: raw
+```
+
+to this in 0.19.x:
+
+```yaml
+companies:
+  type: pandas.CSVDataSet
+  filepath: data/01_raw/companies.csv
+  metadata:
+    kedro-viz:
+      layer: raw
+```
+
+#### Dataset renaming
+In 0.19.0 we renamed dataset and error classes in accordance with the [Kedro lexicon](https://github.com/kedro-org/kedro/wiki/Kedro-documentation-style-guide).
+
+* Dataset classes ending with `DataSet` are replaced by classes that end with `Dataset`.
+* Error classes starting with `DataSet` are replaced by classes that start with `Dataset`.
+
+Note that all of the classes below are also importable from `kedro.io`; only the module where they are defined is listed as the location.
+
+| Type                        | Removed Alias               | Location                       |
+| --------------------------- | --------------------------- | ------------------------------ |
+| `AbstractDataset`           | `AbstractDataSet`           | `kedro.io.core`                |
+| `AbstractVersionedDataset`  | `AbstractVersionedDataSet`  | `kedro.io.core`                |
+| `CachedDataset`             | `CachedDataSet`             | `kedro.io.cached_dataset`      |
+| `LambdaDataset`             | `LambdaDataSet`             | `kedro.io.lambda_dataset`      |
+| `MemoryDataset`             | `MemoryDataSet`             | `kedro.io.memory_dataset`      |
+| `DatasetError`              | `DataSetError`              | `kedro.io.core`                |
+| `DatasetAlreadyExistsError` | `DataSetAlreadyExistsError` | `kedro.io.core`                |
+| `DatasetNotFoundError`      | `DataSetNotFoundError`      | `kedro.io.core`                |
+
+
+#### All other dataset classes are removed from the core Kedro repository (`kedro.extras.datasets`)
+You now need to install and import datasets from the [`kedro-datasets`](https://github.com/kedro-org/kedro-plugins/tree/main/kedro-datasets) package instead.
+
+### Logging
+`logging.yml` is now independent of Kedro's run environment and only used if `KEDRO_LOGGING_CONFIG` is set to point to it. The [documentation on logging](https://docs.kedro.org/en/stable/logging/index.html) describes in detail how logging works in Kedro and how it can be customised.


Code review comments:
diff_hunk: @@ -30,11 +30,18 @@
 * Added documentation about `bootstrap_project` and `configure_project`.
 * Added documentation about `kedro run` and hook execution order.
 
+## Migration guide from Kedro 0.18.* to 0.19.*
+[See the migration guide for 0.19 in the Kedro documentation](https://docs.kedro.org/en/latest/resources/migration.html).
+
 # Release 0.19.1
 
 ## Bug fixes and other changes
 * Loosened pin for `kedro-telemtry` to fix dependency issues in `0.19.0`.
path: RELEASE.md
text: @user1:
```suggestion
* Loosened pin for `kedro-telemetry` to fix dependency issues in `0.19.0`.
```