ci(platform): PAYMENTS-12054 Key the bundler cache on the Gemfile, since there is no lockfile

Author: Willem Homan

.circleci/config.yml

@@ -4,23 +4,38 @@ orbs:
   ci: bigcommerce/internal@volatile
   ruby: bigcommerce/internal-ruby@volatile
 
+# The orb builds its bundler cache key as `<cache_key>-{{ arch }}-{{ checksum <checksumfile> }}` and defaults
+# checksumfile to Gemfile.lock. This repo ships no lockfile, deliberately, so that key cannot be computed:
+# `restore_cache` fails outright and every job installs its gems cold. The failure does not fail the job, so builds stay
+# green and the cost goes unnoticed.
+#
+# The Gemfile is the stable file that does exist. It pins nothing, so the cache is only a warm vendor/bundle to start
+# from and bundler still resolves fresh on every run, which is what a gem wants: CI is the only place a breaking
+# upstream release gets caught.
 defaults: &defaults
   notify_failure: false
+  checksumfile: Gemfile
 
+# cache_key varies per ruby because `{{ arch }}` is OS and CPU, not ruby version. A single bucket shared across 3.3, 3.4
+# and 4.0 would have each job save over the others, and native extensions built against one ruby ABI are not loadable
+# by another.
 ruby_3_3_defaults: &ruby_3_3_defaults
   <<: *defaults
+  cache_key: gem-cache-ruby-3_3
   e:
     name: ruby/ruby
     ruby-version: '3.3'
 
 ruby_3_4_defaults: &ruby_3_4_defaults
   <<: *defaults
+  cache_key: gem-cache-ruby-3_4
   e:
     name: ruby/ruby
     ruby-version: '3.4'
 
 ruby_4_0_defaults: &ruby_4_0_defaults
   <<: *defaults
+  cache_key: gem-cache-ruby-4_0
   e:
     name: ruby/ruby
     ruby-version: '4.0'