add upgrade guide from v3.x to v4.x

Signed-off-by: Bruno Vieira <bruno@chartmogul.com>

4.0-Upgrade.md

@@ -0,0 +1,32 @@
+# Upgrading to chartmogul-ruby 4.0.0
+
+This new version replaces the existing pagination for the `.all()` endpoints that used a combination
+of `page` and `per_page` parameters, and instead uses a `cursor` based pagination. So to list
+(as an example) Plans you now can:
+
+```ruby
+ChartMogul.api_key = '<API key goes here>'
+
+# Getting the first page
+plans = ChartMogul::Plan.all(per_page_ 12)
+
+# This will return an array of plans (if available), and a cursor + has_more fields
+{
+    "plans": [
+        {
+            "uuid": "some_uuid",
+            "data_source_uuid": "some_uuid",
+            "name": "Master Plan"
+        }
+    ],
+    "has_more": True,
+    "cursor": "MjAyMy0wNy0yOFQwODowOToyMi4xNTQyMDMwMDBaJjk0NDQ0Mg=="
+}
+
+if plans.has_more
+  more_plans = plans.next(per_page: 3)
+end
+```
+
+If you have existing code that relies on the `page` parameter, those requests will now throw an error
+alerting you of their deprecation.

README.md

@@ -47,6 +47,7 @@ Or install it yourself as:
     $ gem install chartmogul-ruby
 
 ### Supported Ruby Versions
+
 This gem supports Ruby 2.7 and above.
 
 ## Configuration
@@ -66,6 +67,7 @@ ChartMogul.api_key = '<API key goes here>'
 Thread-safe configuration is used if available, otherwise global is used.
 
 Test your authentication:
+
 ```ruby
 ChartMogul::Ping.ping
 ```
@@ -100,9 +102,11 @@ You can find examples for each endpoint in the ChartMogul [API documentation](ht
 The library will keep retrying if the request exceeds the rate limit or if there's any network related error. By default, the request will be retried for 20 times (approximated 15 minutes) before finally giving up.
 
 You can change the retry count with:
+
 ```ruby
 ChartMogul.max_retries = 15
 ```
+
 Set it to 0 to disable it.
 
 ## Development

changelog.md

@@ -1,5 +1,8 @@
 # chartmogul-ruby Change Log
 
+## Version 4.0.1 - November 7 2023
+- Add upgrade guide from v3.x to v4.x
+
 ## Version 4.0.0 - November 1 2023
 - Remove support for old pagination using `page` parameter.
 - Drop support for Ruby versions below 2.7.

lib/chartmogul/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChartMogul
-  VERSION = '4.0.0'
+  VERSION = '4.0.1'
 end