diff --git a/README.md b/README.md
index b7a683f..8f874e8 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,17 @@
 [![Test workflow](https://img.shields.io/github/workflow/status/docker/build-push-action/test?label=test&logo=github&style=flat-square)](https://github.com/docker/build-push-action/actions?workflow=test)
 [![Codecov](https://img.shields.io/codecov/c/github/docker/build-push-action?logo=codecov&style=flat-square)](https://codecov.io/gh/docker/build-push-action)
 
+## Upgrade
+
+`v2` of this action changes drastically and now uses Docker [Buildx](https://github.com/docker/buildx). It works with
+3 new actions ([login](https://github.com/docker/login-action), [setup-buildx](https://github.com/docker/setup-buildx-action)
+and [setup-qemu](https://github.com/docker/setup-qemu-action)) that we have created. It's also rewritten as a
+[typescript-action](https://github.com/actions/typescript-action/) to be as closed as possible of the
+[GitHub Runner](https://github.com/actions/virtual-environments) during its execution (#71 #92).
+
+[Upgrade notes](UPGRADE.md) and many [usage examples](#usage) have been added to handle most use cases but `v1` is
+still available through [`releases/v1` branch](https://github.com/docker/build-push-action/tree/releases/v1).
+
 ## About
 
 GitHub Action to build and push Docker images with [Buildx](https://github.com/docker/buildx).
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 0000000..54916a0
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,141 @@
+# Upgrade notes
+
+## v1 to v2
+
+* Rename `path` input to `context`
+* Rename `dockerfile` input to `file`
+* Rename `always_pull` input to `pull`
+* Add `builder` input to be able to choose a builder instance through our [setup-buildx action](https://github.com/docker/setup-buildx-action)
+* Add [`platforms`](https://github.com/docker/buildx#---platformvaluevalue) input
+* Add [`allow`](https://github.com/docker/buildx#--allowentitlement) input
+* Add [`load`](https://github.com/docker/buildx#--load) input
+* Add [`outputs`](https://github.com/docker/buildx#-o---outputpath-typetypekeyvalue) input
+* Add [`cache-from`](https://github.com/docker/buildx#--cache-fromnametypetypekeyvalue) input (`cache_froms` removed)
+* Add [`cache-to`](https://github.com/docker/buildx#--cache-tonametypetypekeyvalue) input
+* Add `secrets` input
+* Review `tags` input
+* Remove `repository` input. See [Simple workflow](#simple-workflow) for migration
+* Remove `username`, `password` and `registry` inputs. Login support moved to [docker/login-action](https://github.com/docker/login-action) repo
+* Remove `tag_with_sha`, `tag_with_ref`, `add_git_labels` inputs. See [Tags with ref and Git labels](#tags-with-ref-and-git-labels) for migration
+* Handle Git context
+* Add `digest` output
+
+### Simple workflow
+
+```yaml
+# v1
+steps:
+  -
+    name: Checkout code
+    uses: actions/checkout@v2
+  -
+    name: Build and push Docker images
+    uses: docker/build-push-action@v1
+    with:
+      username: ${{ secrets.DOCKER_USERNAME }}
+      password: ${{ secrets.DOCKER_PASSWORD }}
+      repository: myorg/myrepository
+      always_pull: true
+      build_args: arg1=value1,arg2=value2
+      cache_froms: myorg/myrepository:latest
+      tags: latest
+```
+
+```yaml
+# v2
+steps:
+  -
+    name: Checkout code
+    uses: actions/checkout@v2
+  -
+    name: Set up Docker Buildx
+    uses: docker/setup-buildx-action@v1
+  -
+    name: Login to DockerHub
+    uses: docker/login-action@v1
+    with:
+      username: ${{ secrets.DOCKER_USERNAME }}
+      password: ${{ secrets.DOCKER_PASSWORD }}
+  -
+    name: Build and push
+    uses: docker/build-push-action@v2
+    with:
+      context: .
+      file: ./Dockerfile
+      pull: true
+      push: true
+      build-args: arg1=value1,arg2=value2
+      cache-from: type=registry,ref=myorg/myrepository
+      cache-to: type=registry,ref=myorg/myrepository
+      tags: myorg/myrepository:latest
+```
+
+### Tags with ref and Git labels
+
+```yaml
+# v1
+steps:
+  -
+    name: Checkout code
+    uses: actions/checkout@v2
+  -
+    name: Build and push Docker images
+    uses: docker/build-push-action@v1
+    with:
+      username: ${{ secrets.DOCKER_USERNAME }}
+      password: ${{ secrets.DOCKER_PASSWORD }}
+      repository: myorg/myrepository
+      push: ${{ github.event_name != 'pull_request' }}
+      tag_with_ref: true
+      tag_with_sha: true
+```
+
+```yaml
+# v2
+steps:
+  -
+    name: Checkout
+    uses: actions/checkout@v2
+  -
+    name: Prepare
+    id: prep
+    run: |
+      DOCKER_IMAGE=myorg/myrepository
+      VERSION=edge
+      if [[ $GITHUB_REF == refs/tags/* ]]; then
+        VERSION=${GITHUB_REF#refs/tags/}
+      elif [[ $GITHUB_REF == refs/heads/* ]]; then
+        VERSION=$(echo ${GITHUB_REF#refs/heads/} | sed -r 's#/+#-#g')
+      elif [[ $GITHUB_REF == refs/pull/* ]]; then
+        VERSION=pr-${{ github.event.number }}
+      fi
+      TAGS="${DOCKER_IMAGE}:${VERSION}"
+      if [ "${{ github.event_name }}" = "push" ]; then
+        TAGS="$TAGS,${DOCKER_IMAGE}:sha-${GITHUB_SHA::8}"
+      fi
+      echo ::set-output name=version::${VERSION}
+      echo ::set-output name=tags::${TAGS}
+      echo ::set-output name=created::$(date -u +'%Y-%m-%dT%H:%M:%SZ')
+  -
+    name: Set up Docker Buildx
+    uses: docker/setup-buildx-action@v1
+  -
+    name: Login to DockerHub
+    if: github.event_name != 'pull_request'
+    uses: docker/login-action@v1 
+    with:
+      username: ${{ secrets.DOCKER_USERNAME }}
+      password: ${{ secrets.DOCKER_PASSWORD }}
+  -
+    name: Build and push
+    uses: docker/build-push-action@v2
+    with:
+      context: .
+      file: ./Dockerfile
+      push: ${{ github.event_name != 'pull_request' }}
+      tags: ${{ steps.prep.outputs.tags }}
+      labels: |
+        org.opencontainers.image.source=${{ github.event.repository.clone_url }}
+        org.opencontainers.image.created=${{ steps.prep.outputs.created }}
+        org.opencontainers.image.revision=${{ github.sha }}
+```