Tighten deps, CI, lint config, and release docs for rc1

Author: vipulnsward

.env.example

@@ -1,5 +1,6 @@
 # Uploadcare API credentials
-# Copy this file to .env and fill in your actual keys
+# Copy this file to .env and fill in your actual keys (for local development only).
+# Never commit real credentials. See MIGRATING_V5.md for v5 client-first setup details.
 # Get your keys from: https://app.uploadcare.com/projects/-/api-keys/
 
 UPLOADCARE_PUBLIC_KEY=your_public_key_here

.github/workflows/ruby.yml

@@ -2,7 +2,7 @@
 # They are provided by a third-party and are governed by
 # separate terms of service, privacy policy, and support
 # documentation.
-# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# This workflow installs Ruby, runs tests, and runs style checks in a dedicated job.
 # For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
 
 name: Ruby
@@ -29,10 +29,11 @@ jobs:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: true
     - name: Run tests
-      run: bundle exec rspec
+      # Keep test invocation on rake tasks so repository-local pre/post hooks stay centralized.
+      run: bundle exec rake spec
       env:
         UPLOADCARE_PUBLIC_KEY: demopublickey
-        UPLOADCARE_SECRET_KEY: demoprivatekey
+        UPLOADCARE_SECRET_KEY: demosecretkey
 
   style-check:
     runs-on: ubuntu-latest

.rubocop.yml

@@ -4,7 +4,8 @@ plugins:
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 3.3
+  # RuboCop currently supports up to 3.5; CI still tests this gem on Ruby 4.0.
+  TargetRubyVersion: 3.4
   SuggestExtensions: false
   Exclude:
     - 'examples/**/*'
@@ -81,6 +82,9 @@ Style/FrozenStringLiteralComment:
 Style/ArgumentsForwarding:
   Enabled: false
 
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
 RSpec/ContextWording:
   Prefixes:
     - when
@@ -90,37 +94,17 @@ RSpec/ContextWording:
     - unless
     - for
 
-RSpec/MultipleExpectations:
-  Enabled: false
-
-RSpec/ExampleLength:
-  Enabled: false
-
-RSpec/DescribedClass:
-  Enabled: false
-
-RSpec/DescribeClass:
-  Enabled: false
-
-RSpec/ExpectActual:
-  Enabled: false
-
+# Kept intentionally for API-integration style specs where strict unit-style cops add noise.
 RSpec/AnyInstance:
   Enabled: false
 
-RSpec/SpecFilePathFormat:
-  Enabled: false
-
-RSpec/LeadingSubject:
-  Enabled: false
-
-RSpec/EmptyLineAfterExample:
+RSpec/DescribedClass:
   Enabled: false
 
-RSpec/EmptyLineAfterFinalLet:
+RSpec/ExampleLength:
   Enabled: false
 
-RSpec/EmptyLineAfterExampleGroup:
+RSpec/MultipleExpectations:
   Enabled: false
 
 RSpec/MultipleMemoizedHelpers:
@@ -129,32 +113,15 @@ RSpec/MultipleMemoizedHelpers:
 RSpec/NestedGroups:
   Enabled: false
 
-RSpec/NamedSubject:
-  Enabled: false
-
-RSpec/IteratedExpectation:
+# Existing test suite uses classic doubles/spies heavily; keep these disabled until specs are migrated.
+RSpec/DescribeClass:
   Enabled: false
 
-RSpec/BeEq:
+RSpec/MessageSpies:
   Enabled: false
 
 RSpec/StubbedMock:
   Enabled: false
 
-RSpec/EmptyLineAfterHook:
-  Enabled: false
-
-RSpec/MessageSpies:
-  Enabled: false
-
 RSpec/VerifiedDoubles:
   Enabled: false
-
-RSpec/ReceiveMessages:
-  Enabled: false
-
-RSpec/HookArgument:
-  Enabled: false
-
-RSpec/ClassCheck:
-  Enabled: false

CHANGELOG.md

@@ -51,6 +51,10 @@ Please review [`MIGRATING_V5.md`](./MIGRATING_V5.md) before upgrading from v4.x.
 
 * Support for Ruby versions below `3.3`
 * Legacy configuration and transport patterns that were no longer aligned with the v5 architecture
+### Risk & Rollout Notes
+* Ruby support baseline is now `>= 3.3`; verify application/runtime images before upgrading.
+* Recommended rc1 rollout: wire explicit `Uploadcare::Client` instances first, then migrate call sites incrementally.
+* Keep rollback simple by pinning to the latest v4 release if your app depends on removed internal APIs.
 
 ## 4.5.0 — 2025-07-25
 ### Added

Gemfile

@@ -2,26 +2,25 @@
 
 source 'https://rubygems.org'
 
-# Ruby 3.4+ and 4.0+ compatibility - these gems are no longer in stdlib
-gem 'base64'
-gem 'benchmark' # Required for Ruby 4.0+ compatibility
-gem 'bigdecimal'
-gem 'cgi' # Required for Ruby 4.0+ compatibility
-gem 'mutex_m'
-
 group :development, :test do
+  # Ruby 3.4+ stopped shipping some stdlib components as default gems.
+  if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.4')
+    gem 'base64', require: false
+    gem 'cgi', require: false
+  end
+
+  # Ruby 4.1+ removes tsort from default gems.
+  gem('tsort', require: false) if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('4.1')
+
   gem 'byebug'
   gem 'dotenv', '~> 3.2' # For running examples with .env file
-  gem 'irb'
   gem 'rake'
-  gem 'rdoc'
   gem 'redcarpet'
   gem 'rspec'
   gem 'rubocop'
   gem 'rubocop-rake'
   gem 'rubocop-rspec'
   gem 'simplecov', require: false
-  gem 'tsort', require: false
   gem 'vcr'
   gem 'webmock'
   gem 'yard'

MIGRATING_V5.md

@@ -19,6 +19,10 @@ Version 5 introduces:
 - a modernized internal structure built around Zeitwerk and Faraday
 
 Version 5 also raises the minimum supported Ruby version to `3.3`.
+The CI matrix for v5 verifies `3.3`, `3.4`, and `4.0`.
+
+If you run examples locally with `.env`, use it only for developer machines and never commit real keys.
+The examples expect `UPLOADCARE_PUBLIC_KEY` and `UPLOADCARE_SECRET_KEY` to come from environment variables.
 
 ## Recommended Migration Order
 

lib/uploadcare/operations/multipart_upload.rb

@@ -104,7 +104,7 @@ def upload_parts_sequential(file, presigned_urls, part_size, &block)
     end
   end
 
-  def upload_parts_parallel(file, presigned_urls, part_size, threads, &block)
+  def upload_parts_parallel(file, presigned_urls, part_size, threads, &)
     total_size = file.respond_to?(:size) ? file.size : ::File.size(file.path)
     uploaded = { value: 0 }
     mutex = Mutex.new
@@ -131,26 +131,26 @@ def upload_parts_parallel(file, presigned_urls, part_size, threads, &block)
 
     workers = threads.times.map do
       Thread.new do
-        run_parallel_worker(worker_context, &block)
+        run_parallel_worker(worker_context, &)
       end
     end
 
     workers.each(&:join)
     raise errors.first if errors.any?
   end
 
-  def run_parallel_worker(context, &block)
+  def run_parallel_worker(context, &)
     ::File.open(context[:file_path], 'rb') do |worker_file|
-      process_parallel_jobs(worker_file, context, &block)
+      process_parallel_jobs(worker_file, context, &)
     rescue StandardError => e
       record_parallel_error(context, e)
     end
   end
 
-  def process_parallel_jobs(worker_file, context, &block)
+  def process_parallel_jobs(worker_file, context, &)
     loop do
       job = context[:queue].pop
-      break unless process_parallel_job(worker_file, context, job, &block)
+      break unless process_parallel_job(worker_file, context, job, &)
     end
   end
 

spec/uploadcare/api/rest/addons_spec.rb

@@ -3,6 +3,8 @@
 require 'spec_helper'
 
 RSpec.describe Uploadcare::Api::Rest::Addons do
+  subject(:addons) { described_class.new(rest: rest) }
+
   let(:config) do
     Uploadcare::Configuration.new(
       public_key: 'demopublickey',
@@ -15,8 +17,6 @@
 
   let(:rest) { Uploadcare::Api::Rest.new(config: config) }
 
-  subject(:addons) { described_class.new(rest: rest) }
-
   describe '#initialize' do
     it 'stores the rest client' do
       expect(addons.rest).to eq(rest)

spec/uploadcare/api/rest/document_conversions_spec.rb

@@ -3,6 +3,8 @@
 require 'spec_helper'
 
 RSpec.describe Uploadcare::Api::Rest::DocumentConversions do
+  subject(:document_conversions) { described_class.new(rest: rest) }
+
   let(:config) do
     Uploadcare::Configuration.new(
       public_key: 'demopublickey',
@@ -14,8 +16,6 @@
 
   let(:rest) { Uploadcare::Api::Rest.new(config: config) }
 
-  subject(:document_conversions) { described_class.new(rest: rest) }
-
   describe '#initialize' do
     it 'stores the rest client' do
       expect(document_conversions.rest).to eq(rest)

spec/uploadcare/api/rest/file_metadata_spec.rb

@@ -3,6 +3,8 @@
 require 'spec_helper'
 
 RSpec.describe Uploadcare::Api::Rest::FileMetadata do
+  subject(:file_metadata) { described_class.new(rest: rest) }
+
   let(:config) do
     Uploadcare::Configuration.new(
       public_key: 'demopublickey',
@@ -14,8 +16,6 @@
 
   let(:rest) { Uploadcare::Api::Rest.new(config: config) }
 
-  subject(:file_metadata) { described_class.new(rest: rest) }
-
   describe '#initialize' do
     it 'stores the rest client' do
       expect(file_metadata.rest).to eq(rest)