From 010787fc9c8c9526e9e4f4854e9e994753b7def4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20V=C3=A1squez?= <juan@ombulabs.com>
Date: Wed, 27 May 2026 12:45:57 -0600
Subject: [PATCH] docs: explain BUNDLE_GEMFILE usage for the next Gemfile

Document how the `next` wrapper sets BUNDLE_GEMFILE, how to set it
directly when the wrapper is not an option (CI, IDE, Docker), the
conservative update pattern for Gemfile.next.lock, and the reminder to
keep Gemfile.lock and Gemfile.next.lock in sync.
---
 README.md | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d0c51e0..bd7cad6 100644
--- a/README.md
+++ b/README.md
@@ -51,9 +51,49 @@ vim Gemfile
 next bundle install
 
 # Start your server using the next Gemfile
-next rails s
+next rails server
 ```
 
+### How `next` works (and using `BUNDLE_GEMFILE` directly)
+
+The `next` command is a thin wrapper. It runs your command with `BUNDLE_GEMFILE`
+set so Bundler reads the next dependency set instead of the default one. So these
+two are equivalent:
+
+```bash
+next rails server
+
+BUNDLE_GEMFILE=Gemfile.next rails server
+```
+
+Set `BUNDLE_GEMFILE=Gemfile.next` directly when you can't use the `next` wrapper,
+for example in CI jobs, IDE run configurations, Docker, or other tooling that
+calls Bundler on its own:
+
+```bash
+# Run the test suite against the next Gemfile in CI
+BUNDLE_GEMFILE=Gemfile.next bundle exec rspec
+
+# Export it for a whole shell session
+export BUNDLE_GEMFILE=Gemfile.next
+bundle install
+rails server
+```
+
+When updating `Gemfile.next.lock`, prefer a conservative update so you only bump
+what you intend to and keep the diff small:
+
+```bash
+# Update a single gem against the next Gemfile, leaving everything else pinned
+BUNDLE_GEMFILE=Gemfile.next bundle update rails --conservative
+```
+
+> [!IMPORTANT]
+> Whenever you update `Gemfile.lock`, update `Gemfile.next.lock` at the same time
+> (run the equivalent command with `BUNDLE_GEMFILE=Gemfile.next`). Keeping the two
+> lockfiles in sync avoids surprising differences between the current and next
+> dependency sets.
+
 ### Conditional code
 
 When your Gemfile targets two versions, you may need to branch application code as well: