From fc92fd532cd5d4b10de86dfb956642428a1371ea Mon Sep 17 00:00:00 2001
From: Neur0toxine <pashok9825@gmail.com>
Date: Wed, 27 Oct 2021 14:23:16 +0300
Subject: [PATCH] UPGRADING.md

---
 README.md    |  6 ++++-
 UPGRADING.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 UPGRADING.md

diff --git a/README.md b/README.md
index 449868e..9ebb481 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
 
 This is golang RetailCRM API client.
 
-## Install
+## Installation
 
 ```bash
 go get -u github.com/retailcrm/api-client-go/v2
@@ -158,3 +158,7 @@ func main() {
 	log.Println("Available scopes:", strings.Join(resp.Scopes, ", "))
 }
 ```
+
+## Upgrading
+
+Please check the [UPGRADING.md](UPGRADING.md) to learn how to upgrade to the new version.
diff --git a/UPGRADING.md b/UPGRADING.md
new file mode 100644
index 0000000..ba68226
--- /dev/null
+++ b/UPGRADING.md
@@ -0,0 +1,70 @@
+# Upgrading to the v2
+
+### Install the new version
+
+```bash
+go get -u github.com/retailcrm/api-client-go/v2
+```
+
+### Update all imports
+
+Before:
+```go
+package main
+
+import v5 "github.com/retailcrm/api-client-go/v5"
+```
+
+After:  
+```go
+package main
+
+import "github.com/retailcrm/api-client-go/v2"
+```
+
+You can use package alias `v5` to skip the second step.
+
+### Replace package name for all imported symbols
+
+Before:
+
+```go
+package main
+
+import v5 "github.com/retailcrm/api-client-go/v5"
+
+func main() {
+    client := v5.New("https://test.retailcrm.pro", "key")
+	data, status, err := client.Orders(v5.OrdersRequest{
+		Filter: v5.OrdersFilter{
+			City: "Moscow",
+		},
+		Page: 1,
+	})
+	...
+}
+```
+
+After:
+
+```go
+package main
+
+import "github.com/retailcrm/api-client-go/v2"
+
+func main() {
+    client := retailcrm.New("https://test.retailcrm.pro", "key")
+	data, status, err := client.Orders(retailcrm.OrdersRequest{
+		Filter: retailcrm.OrdersFilter{
+			City: "Moscow",
+		},
+		Page: 1,
+	})
+	...
+}
+```
+
+### Upgrade client usages
+
+This major release contains some breaking changes regarding field names and fully redesigned error handling. Use the second example from 
+the readme to learn how to process errors correctly.