From 617f2ed44e45d45b07161d3f194c3c324ef0511e Mon Sep 17 00:00:00 2001
From: Martin Wentzel <martin.wentzel@kreuzwerker.de>
Date: Mon, 9 Jan 2023 11:45:29 +0100
Subject: [PATCH] docs: Update documentation.

---
 docs/resources/registry_image.md |  2 +-
 docs/v2_v3_migration.md          | 47 ++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 docs/v2_v3_migration.md

diff --git a/docs/resources/registry_image.md b/docs/resources/registry_image.md
index bebf9bc5..60d85593 100644
--- a/docs/resources/registry_image.md
+++ b/docs/resources/registry_image.md
@@ -33,7 +33,7 @@ resource "docker_registry_image" "helloworld" {
 
 ### Optional
 
-- `build` (Block List, Max: 1, Deprecated) Definition for building the image (see [below for nested schema](#nestedblock--build))
+- `build` (Block List, Max: 1, Deprecated) This field is deprecated. Use the `build` block of the `docker_image` resource instead. This field will be removed in the next major release. (see [below for nested schema](#nestedblock--build))
 - `insecure_skip_verify` (Boolean) If `true`, the verification of TLS certificates of the server/registry is disabled. Defaults to `false`
 - `keep_remotely` (Boolean) If true, then the Docker image won't be deleted on destroy operation. If this is false, it will delete the image from the docker registry on destroy operation. Defaults to `false`
 - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the `docker_registry_image` resource to be replaced. This can be used to repush a local image
diff --git a/docs/v2_v3_migration.md b/docs/v2_v3_migration.md
new file mode 100644
index 00000000..9e3d7501
--- /dev/null
+++ b/docs/v2_v3_migration.md
@@ -0,0 +1,47 @@
+# V2 to V3 Migration Guide
+
+This guide is intended to help you migrate from V2 to V3 of the `terraform-provider-docker`.
+
+The in the past minor versions there were many new attributes and older attributes are deprecated. 
+
+This will give you an overview over which attributes are deprecated and which attributes you should use instead.
+
+## `docker_container`
+
+
+Deprecated attributes:
+* `links`: The --link flag is a legacy feature of Docker and will be removed (https://docs.docker.com/network/links/)
+* `ip_address`, `ip_prefix_length`, `gateway`: Use the `network_data` block instead
+* `network_alias`, `networks`: Use the `networks_addvanced` block instead
+
+
+## `docker_image`
+
+* `latest`: Use `repo_digest` instead
+* `pull_trigger`: Use `pull_triggers` instead
+* `output`: Unused and will be removed
+* `build.path`: Use `build.context` instead
+
+## `docker_service`
+
+* `networks`: Use the `networks_addvanced` block instead
+
+
+## `docker_registry_image`
+
+The whole `build` block will be removed. Use the `build` block of the `docker_image` resource instead.
+In order to push images to an registry, still use `docker_registry_image` and reference the `docker_image` resource:
+
+```hcl
+resource "docker_image" "foo_image" {
+  provider = "docker.private"
+  name     = "somename"
+  build {
+   // your build params
+  }
+}
+
+resource "docker_registry_image" "foo" {
+  name                 = docker_image.foo_image.name
+}
+```
\ No newline at end of file