From 2ed1719264f0d8910001d8da3acf9330cc70fd96 Mon Sep 17 00:00:00 2001
From: "Erik Trapin (ecoologic)" <erik.trapin@zendesk.com>
Date: Mon, 21 Aug 2023 11:04:07 +1000
Subject: [PATCH] Doc improvement

---
 README.md                     | 25 +++++++++++++++++++++++--
 lib/zendesk_api/collection.rb |  6 +++---
 2 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 01bbb791..5588f0da 100644
--- a/README.md
+++ b/README.md
@@ -166,7 +166,17 @@ zendesk_api_client_rb $ bundle console
 `ZendeskAPI::Collections` can be paginated:
 
 ```ruby
+# Note that CBP (cursor based pagination) is the default and preferred way
+# and has fewer limitations on deep pagination
+tickets = client.tickets.per_page(3)
+page1 = tickets.fetch! # GET /api/v2/tickets?page[after]={cursor}&page[size]=3
+page2 = tickets.next # GET /api/v2/tickets?page[after]={cursor}&page[size]=3
+# ...
+
+# OR...
+# Note that OBP (offset based pagination) can incur to various limitations
 tickets = client.tickets.page(2).per_page(3)
+
 next_page = tickets.next # => 3
 tickets.fetch! # GET /api/v2/tickets?page=3&per_page=3
 previous_page = tickets.prev # => 2
@@ -221,7 +231,7 @@ ticket.attributes # => { "priority" => "urgent" }
 ticket.save! # Will PUT => true
 ticket.destroy! # => true
 
-ZendeskAPI::Ticket.new(client, { :priority => "urgent" })
+ZendeskAPI::Ticket.new(client, { priority: "urgent" })
 ticket.new_record? # => true
 ticket.save! # Will POST
 ```
@@ -455,7 +465,7 @@ bundle exec rubocop # Runs the lint (use `--fix` for autocorrect)
 
 1. Fork the project.
 2. Make your feature addition or bug fix.
-3. Add tests for it. This is important so that we don't break it in a future
+3. **Add tests for it**. This is important so that we don't break it in a future
    version unintentionally.
 4. Commit. Do not alter `Rakefile`, version, or history. (If you want to have
    your own version, that is fine, but bump version in a commit by itself that
@@ -464,6 +474,17 @@ bundle exec rubocop # Runs the lint (use `--fix` for autocorrect)
 
 **Note:** Live specs will likely fail for external contributors. The Zendesk devs can help with that. If you have permissions and some live specs unexpectedly fail, that might be a data error, see the REPL for that.
 
+## Merging contributors pull requests
+
+External contributions don't run live specs, so we need to use a workaround. Assuming a PR from `author:author/branch` to `default_branch`:
+
+1. Create a branch in our repo `author_branch`
+2. Change the destination branch of the PR to `author_branch`
+3. Merge
+4. Create a pr in our repo from `default_branch`
+   - Make sure they know the commits still carry their name
+   - [Example](https://github.com/zendesk/zendesk_api_client_rb/pull/553)
+
 ## Copyright and license
 
 Copyright 2015-2023 Zendesk
diff --git a/lib/zendesk_api/collection.rb b/lib/zendesk_api/collection.rb
index 35fff009..9c21079e 100644
--- a/lib/zendesk_api/collection.rb
+++ b/lib/zendesk_api/collection.rb
@@ -225,7 +225,7 @@ def next
         clear_cache
         @options["page"] = @options["page"].to_i + 1
       elsif (@query = @next_page)
-        # Send _only_ url param "?after=token" to get the next page
+        # Send _only_ url param "?page[after]=token" to get the next page
         @options.page&.delete("before")
         fetch(true)
       else
@@ -243,7 +243,7 @@ def prev
         clear_cache
         @options["page"] -= 1
       elsif (@query = @prev_page)
-        # Send _only_ url param "?before=token" to get the prev page
+        # Send _only_ url param "?page[before]=token" to get the prev page
         @options.page&.delete("after")
         fetch(true)
       else
@@ -465,7 +465,7 @@ def array_method(name, *args, &block)
     def next_collection(name, *args, &block)
       opts = args.last.is_a?(Hash) ? args.last : {}
       opts.merge!(collection_path: [*@collection_path, name], page: nil)
-      # why page: nil ?
+      # Why `page: nil`?
       # when you do client.tickets.fetch followed by client.tickets.foos => the request to /tickets/foos will
       # have the options page set to whatever the last options were for the tickets collection
       self.class.new(@client, @resource_class, @options.merge(opts))