Enhance README and code comments for clarity on rate limits and throttling behavior

Author: thedave42

api/ruby/find-inactive-members/README.md

@@ -32,8 +32,10 @@ gem install octokit faraday
 
 The `OCTOKIT_ACCESS_TOKEN` is required in order to see activities on private repositories. Also note that GitHub.com has an rate limit of 60 unauthenticated requests per hour, which this tool can easily exceed. Access tokens can be generated at https://github.com/settings/tokens. The `OCTOKIT_API_ENDPOINT` isn't required if connecting to GitHub.com, but is required if connecting to a GitHub Enterprise instance.
 
+`OCTOKIT_ACCESS_TOKEN` needs the scopes `read:org`, `read:user`, `repo`, and `user:email`.
+
 ```shell
-export OCTOKIT_ACCESS_TOKEN=00000000000000000000000     # Required if looking for activity in private repositories.
+export OCTOKIT_ACCESS_TOKEN=00000000000000000000000     # Required if looking for activity in private repositories. 
 export OCTOKIT_API_ENDPOINT="https://<your_github_enterprise_instance>/api/v3" # Not required if connecting to GitHub.com.
 ```
 
@@ -55,3 +57,17 @@ Members are defined as inactive if they **have not performed** any of the follow
 - Merged or pushed commits into the default branch
 - Opened an Issue or Pull Request
 - Commented on an Issue or Pull Request
+
+## Rate Limit
+
+The script will use the following rate limit headers returned by the API to throttle requests in order to stay within the rate limit.  You can disable throttling using the `-t` option.
+
+| Header name | Description |
+| --- | --- |
+| `x-ratelimit-limit` | The maximum number of requests that you can make per hour |
+| `x-ratelimit-remaining` | The number of requests remaining in the current rate limit window |
+| `x-ratelimit-used` | The number of requests you have made in the current rate limit window |
+| `x-ratelimit-reset` | The time at which the current rate limit window resets, in UTC epoch seconds |
+| `x-ratelimit-resource` | The rate limit resource that the request counted against. |
+
+For more information about the different resources, see [REST API endpoints for rate limits](https://docs.github.com/en/rest/rate-limit/rate-limit#get-rate-limit-status-for-the-authenticated-user). 

api/ruby/find-inactive-members/find_inactive_members.rb

@@ -112,7 +112,7 @@ def throttle_request
       elapsed_hour = @last_request_time - @hour_start_time
       current_rate = elapsed_hour > 0 ? (@request_count / elapsed_hour * 3600).round(1) : 0
       github_info = @github_rate_limit_remaining ? " GitHub: #{@github_rate_limit_remaining} remaining" : ""
-      $stderr.print "Throttling status: #{@request_count} requests in #{elapsed_hour.round(1)}s (#{current_rate}/hour rate)#{github_info}\n"
+      $stderr.print "\nThrottling status: #{@request_count} requests in #{elapsed_hour.round(1)}s (#{current_rate}/hour rate)#{github_info}\n"
     end
   end
 
@@ -122,7 +122,7 @@ def log_throttle_status
 
     elapsed_hour = Time.now - @hour_start_time
     rate_per_hour = elapsed_hour > 0 ? (@request_count / elapsed_hour * 3600).round(1) : 0
-    $stderr.print "Throttle debug: #{@request_count} requests in last #{elapsed_hour.round(1)}s (#{rate_per_hour}/hour rate)\n"
+    $stderr.print "\nThrottle debug: #{@request_count} requests in last #{elapsed_hour.round(1)}s (#{rate_per_hour}/hour rate)\n"
   end
 end
 
@@ -179,7 +179,7 @@ def check_rate_limit
     rate_limit = retry_on_403("checking rate limit") do
       @client.rate_limit
     end
-    info "Rate limit: #{rate_limit.remaining}/#{rate_limit.limit}\n"
+    info "\nRate limit: #{rate_limit.remaining}/#{rate_limit.limit}\n"
     info "Rate limit resets at: #{rate_limit.resets_at}\n"
     info "Throttling: Limited to #{ThrottleMiddleware::MAX_REQUESTS_PER_HOUR} requests/hour (#{ThrottleMiddleware::MIN_DELAY_SECONDS.round(2)}s min delay)\n"
   end
@@ -222,7 +222,7 @@ def retry_on_403(description, max_retries = 3)
         return yield
       rescue Octokit::Forbidden => e
         retries += 1
-        info "⚠️  403 Forbidden error occurred while #{description}\n"
+        info "\n⚠️  403 Forbidden error occurred while #{description}\n"
 
         if retries <= max_retries
           info "🔄 Waiting 5 seconds before retry #{retries}/#{max_retries}...\n"
@@ -507,7 +507,6 @@ def member_activity
   end
 
   opts.on('-t', '--no-throttle', "Disable API request throttling (use with caution)") do |t|
-    puts "DEBUG: -t flag was triggered, t value = #{t.inspect}"
     options[:no_throttle] = true
   end