diff --git a/README.md b/README.md
index 81f781d..6b86be8 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,10 @@
 [![Become a sponsor](https://img.shields.io/badge/sponsor-crazy--max-181717.svg?logo=github&style=flat-square)](https://github.com/sponsors/crazy-max)
 [![Paypal Donate](https://img.shields.io/badge/donate-paypal-00457c.svg?logo=paypal&style=flat-square)](https://www.paypal.me/crazyws)
 
+## Upgrade from v1
+
+`v2` of this action includes significant changes. Please read the [upgrade notes](UPGRADE.md) for a smooth migration.
+
 ## About
 
 GitHub Action to extract metadata (tags, labels) for Docker. This action is particularly useful if used with
@@ -50,13 +54,11 @@ on:
   push:
     branches:
       - 'master'
-      - 'releases/v*'
     tags:
       - 'v*'
   pull_request:
     branches:
       - 'master'
-      - 'releases/v*'
 
 jobs:
   docker:
@@ -105,13 +107,11 @@ on:
   push:
     branches:
       - 'master'
-      - 'releases/v*'
     tags:
       - 'v*'
   pull_request:
     branches:
       - 'master'
-      - 'releases/v*'
 
 jobs:
   docker:
@@ -512,14 +512,14 @@ tags: |
 
 ```yaml
 tags: |
-  type=raw,value=mytag1
-  type=raw,value=mytag2
+  type=raw,value=foo
+  type=raw,value=bar
   # or
-  type=raw,mytag1
-  type=raw,mytag2
+  type=raw,foo
+  type=raw,bar
   # or
-  mytag1
-  mytag2
+  foo
+  bar
 ```
 
 Output custom tags according to your needs.
@@ -528,7 +528,7 @@ Extended attributes and default values:
 
 ```yaml
 tags: |
-  type=raw,enable=true,priority=200,prefix=,suffix=,value=mytag1
+  type=raw,enable=true,priority=200,prefix=,suffix=,value=
 ```
 
 ### `type=sha`
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 0000000..f6d5e52
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,295 @@
+# Upgrade notes
+
+## v1 to v2
+
+* [inputs](#inputs)
+  * [`tag-sha`](#tag-sha)
+  * [`tag-edge` / `tag-edge-branch`](#tag-edge--tag-edge-branch)
+  * [`tag-semver`](#tag-semver)
+  * [`tag-match` / `tag-match-group`](#tag-match--tag-match-group)
+  * [`tag-latest`](#tag-latest)
+  * [`tag-schedule`](#tag-schedule)
+  * [`tag-custom` / `tag-custom-only`](#tag-custom--tag-custom-only)
+  * [`label-custom`](#label-custom)
+* [Basic workflow](#basic-workflow)
+* [Semver workflow](#semver-workflow)
+
+### inputs
+
+| New        | Unchanged       | Removed            |
+|------------|-----------------|--------------------|
+| `tags`     | `images`        | `tag-sha`          |
+| `flavor`   | `sep-tags`      | `tag-edge`         |
+| `labels`   | `sep-labels`    | `tag-edge-branch`  |
+|            |                 | `tag-semver`       |
+|            |                 | `tag-match`        |
+|            |                 | `tag-match-group`  |
+|            |                 | `tag-latest`       |
+|            |                 | `tag-schedule`     |
+|            |                 | `tag-custom`       |
+|            |                 | `tag-custom-only`  |
+|            |                 | `label-custom`     |
+
+#### `tag-sha`
+
+```yaml
+tags: |
+  type=sha
+```
+
+#### `tag-edge` / `tag-edge-branch`
+
+```yaml
+tags: |
+  # default branch
+  type=edge
+  # specify branch
+  type=edge,branch=main
+```
+
+#### `tag-semver`
+
+```yaml
+tags: |
+  type=semver,pattern={{version}}
+```
+
+#### `tag-match` / `tag-match-group`
+
+```yaml
+tags: |
+  type=match,pattern=v(.*),group=1
+```
+
+#### `tag-latest`
+
+`tag-latest` is now handled through the [`flavor` input](README.md#flavor-input):
+
+```yaml
+flavor: |
+  latest=auto
+```
+
+See also the notes about ["latest tag" behavior](README.md#latest-tag)
+
+#### `tag-schedule`
+
+```yaml
+tags: |
+  # default tag (nightly)
+  type=schedule
+  # specific pattern
+  type=schedule,pattern={{date 'YYYYMMDD'}}
+```
+
+#### `tag-custom` / `tag-custom-only`
+
+```yaml
+tags: |
+  type=raw,value=foo
+  type=raw,value=bar
+  # or
+  type=raw,foo
+  type=raw,bar
+  # or
+  foo
+  bar
+```
+
+#### `label-custom`
+
+Same behavior for `labels`:
+
+```yaml
+labels: |
+  maintainer=CrazyMax
+```
+
+### Basic workflow
+
+```yaml
+# v1
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Docker meta
+        id: meta
+        uses: crazy-max/ghaction-docker-meta@v1
+        with:
+          images: name/app
+      -
+        name: Login to DockerHub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      -
+        name: Build and push
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.docker_meta.outputs.tags }}
+          labels: ${{ steps.docker_meta.outputs.labels }}
+```
+
+```yaml
+# v2
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Docker meta
+        id: meta
+        uses: crazy-max/ghaction-docker-meta@v2
+        with:
+          images: name/app
+      -
+        name: Login to DockerHub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      -
+        name: Build and push
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+```
+
+### Semver workflow
+
+```yaml
+# v1
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Docker meta
+        id: meta
+        uses: crazy-max/ghaction-docker-meta@v1
+        with:
+          images: name/app
+          tag-semver: |
+            {{version}}
+            {{major}}.{{minor}}
+      -
+        name: Login to DockerHub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      -
+        name: Build and push
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+```
+
+```yaml
+# v2
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Docker meta
+        id: meta
+        uses: crazy-max/ghaction-docker-meta@v2
+        with:
+          images: name/app
+          tags: |
+            type=ref,event=branch
+            type=ref,event=tag
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+      -
+        name: Login to DockerHub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      -
+        name: Build and push
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+```