rubyworks · trans · Sep 27, 2026 · Sep 27, 2026
diff --git a/HISTORY.md b/HISTORY.md
@@ -1,6 +1,12 @@
 # Facets Release History
 
-## Unreleased
+## 4.0.0 / 2026-09-27
+
+A major release, because it changes behavior: `Kernel#try!` is now the
+lenient variant and `#try` is strict, `require 'facets'` no longer loads
+`Kernel#with`, and Rails-compatible methods move to the new `lib/rails`
+area (still loaded by `require 'facets'` with a warning until 2027-09-30).
+Every deprecation now names that same removal date.
 
 Changes:
 
@@ -84,6 +90,10 @@ Changes:
   * Fix the qed demos, which had 8 failures and 2 errors. Most were stale
     expectations (`Array#from`, `#step`, `#arrange`, `String#similarity`)
     and the date demo held pasted irb output.
+  * CONTRIBUTING.md explains the test stack (RubyTest, Lemon, AE and QED)
+    and the `@uncommon` convention.
+  * The `String#trim` demo no longer drops random cases, so the QED
+    assertion count is the same on every run.
 
 ## 3.2.2 / 2026-06-15
 

diff --git a/README.md b/README.md
@@ -64,7 +64,7 @@ This loads `ostruct` and Facets' OpenStruct extensions. On Ruby 3.5+, declare th
 - [Generated API documentation on RubyDoc.info](https://www.rubydoc.info/gems/facets) (check the displayed version)
 - [Release history](HISTORY.md)
 
-In the published 3.2.2 gem, the split between `lib/core` and `lib/standard` is visible in API source paths. This helps you tell whether a method is loaded by `require 'facets'` or needs an explicit require. The development branch also has a new `lib/rails` area for Rails-compatible helpers; see the **Unreleased** section of the release history for details.
+The split between `lib/core`, `lib/standard` and `lib/rails` is visible in API source paths. This helps you tell whether a method is loaded by `require 'facets'` or needs an explicit require. The `lib/rails` area, new in 4.0.0, holds Rails-compatible helpers; see the release history for details.
 
 ## Contribute
 

diff --git a/docs/_src/index.erb b/docs/_src/index.erb
@@ -8,7 +8,7 @@
         <a class="button button-primary" href="learn.html">Get started <span aria-hidden="true">↗</span></a>
         <a class="button button-outline" href="https://github.com/rubyworks/facets">Explore the source <span aria-hidden="true">↗</span></a>
       </div>
-      <p class="hero-note">Version <strong>3.2.2</strong> <span aria-hidden="true">·</span> Ruby <strong>3.1+</strong> <span aria-hidden="true">·</span> BSD 2-Clause</p>
+      <p class="hero-note">Version <strong>4.0.0</strong> <span aria-hidden="true">·</span> Ruby <strong>3.1+</strong> <span aria-hidden="true">·</span> BSD 2-Clause</p>
     </div>
     <div class="hero-visual" aria-label="Ruby Facets code example">
       <div class="orbit orbit-one"></div><div class="orbit orbit-two"></div>
@@ -51,5 +51,5 @@
 </section>
 
 <section class="section release-section">
-  <div class="shell release-grid"><div><p class="kicker kicker-light">LATEST RELEASE</p><h2>Fresh facets<br>for modern Ruby.</h2><p>Version 3.2.2 includes compatibility fixes across Ruby 3.1–3.4, following the 3.2 modernization release.</p><a class="button button-light" href="news.html">Read the release notes <span aria-hidden="true">↗</span></a></div><div class="release-stamp"><span class="release-stamp-small">RUBY FACETS</span><strong>3.2.2</strong><span>JUNE 2026</span></div></div>
+  <div class="shell release-grid"><div><p class="kicker kicker-light">LATEST RELEASE</p><h2>Fresh facets<br>for modern Ruby.</h2><p>Version 4.0.0 makes <code>#try</code> strict and <code>#try!</code> lenient, adds a <code>lib/rails</code> area for Rails-compatible methods, and gives every deprecation a removal date.</p><a class="button button-light" href="news.html">Read the release notes <span aria-hidden="true">↗</span></a></div><div class="release-stamp"><span class="release-stamp-small">RUBY FACETS</span><strong>4.0.0</strong><span>SEPTEMBER 2026</span></div></div>
 </section>
diff --git a/docs/_src/learn.erb b/docs/_src/learn.erb
@@ -1,6 +1,6 @@
 <section class="page-hero"><div class="shell"><p class="eyebrow"><span class="eyebrow-line"></span> THE GUIDE</p><h1>Find your way<br><em>into Facets.</em></h1><p>Install the gem, choose how much to load, and make Ruby feel a little more like yours.</p></div></section>
 <section class="section section-light"><div class="shell guide-grid"><aside class="guide-aside"><p class="kicker">ON THIS PAGE</p><a href="#install">Install</a><a href="#load">Load extensions</a><a href="#examples">Try a few methods</a><a href="#reference">Find the API</a></aside><div class="guide-content">
-  <section id="install" class="guide-block"><p class="kicker">01 / GET READY</p><h2>Install Facets</h2><p>Facets 3.2.2 requires Ruby 3.1 or newer. Install it directly with RubyGems or add it to a Bundler project.</p><div class="snippet"><div class="snippet-label">TERMINAL</div><pre><code>gem install facets</code></pre></div><div class="snippet"><div class="snippet-label">GEMFILE</div><pre><code>gem 'facets', require: false</code></pre></div><p><code>require: false</code> keeps Bundler from loading the entire core collection automatically, so you can choose the files your project needs.</p></section>
+  <section id="install" class="guide-block"><p class="kicker">01 / GET READY</p><h2>Install Facets</h2><p>Facets 4.0.0 requires Ruby 3.1 or newer. Install it directly with RubyGems or add it to a Bundler project.</p><div class="snippet"><div class="snippet-label">TERMINAL</div><pre><code>gem install facets</code></pre></div><div class="snippet"><div class="snippet-label">GEMFILE</div><pre><code>gem 'facets', require: false</code></pre></div><p><code>require: false</code> keeps Bundler from loading the entire core collection automatically, so you can choose the files your project needs.</p></section>
   <section id="load" class="guide-block"><p class="kicker">02 / CHOOSE YOUR SCOPE</p><h2>Load what fits</h2><p>Most core extension methods are stored in individual files. You can require one method, a class's core methods, or the core collection.</p><div class="snippet"><div class="snippet-label">RUBY</div><pre><code><span class="code-comment"># One method</span>
 require 'facets/array/to_ranges'
 

diff --git a/docs/_src/news.erb b/docs/_src/news.erb
@@ -1,6 +1,7 @@
 <section class="page-hero"><div class="shell"><p class="eyebrow"><span class="eyebrow-line"></span> RELEASES & HISTORY</p><h1>A living Ruby<br><em>collection.</em></h1><p>Facets has been growing since 2004. Here are the recent releases and a path back through its story.</p></div></section>
-<section class="section section-light"><div class="shell"><div class="section-heading narrow"><p class="kicker">LATEST RELEASES</p><h2>Facets 3.2</h2><p>The 3.2 series brings the library forward for Ruby 3.1 and newer. Work merged since 3.2.2 is listed under <a href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#unreleased">Unreleased</a> in the release history.</p></div><div class="timeline">
-  <article class="timeline-item" id="facets-3-2-2"><div class="timeline-date"><strong>3.2.2</strong><span>15 JUN 2026</span></div><div><p class="tag">LATEST</p><h3>Compatibility, polished</h3><p>Fixes range intersection on Ruby 3.1 and 3.2, restores <code>Range#overlap?</code> where Ruby does not provide it, and corrects <code>Binding#caller_locations</code> argument handling.</p><a class="text-link" href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#322--2026-06-15">Read changes <span aria-hidden="true">↗</span></a></div></article>
+<section class="section section-light"><div class="shell"><div class="section-heading narrow"><p class="kicker">LATEST RELEASES</p><h2>Facets 4.0</h2><p>Facets 4.0 continues the modernization begun in 3.2 for Ruby 3.1 and newer. The 3.2.0 release changed enough that it should have been 4.0.0; 4.0.0 makes the next round of changes under the right number.</p></div><div class="timeline">
+  <article class="timeline-item" id="facets-4-0-0"><div class="timeline-date"><strong>4.0.0</strong><span>27 SEP 2026</span></div><div><p class="tag">LATEST</p><h3>Clearer by design</h3><p>Makes <code>#try</code> strict and <code>#try!</code> lenient, moves Rails-compatible methods to a new <code>lib/rails</code> area, and schedules every deprecation for removal after 2027-09-30.</p><a class="text-link" href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#400--2026-09-27">Read changes <span aria-hidden="true">↗</span></a></div></article>
+  <article class="timeline-item" id="facets-3-2-2"><div class="timeline-date"><strong>3.2.2</strong><span>15 JUN 2026</span></div><div><h3>Compatibility, polished</h3><p>Fixes range intersection on Ruby 3.1 and 3.2, restores <code>Range#overlap?</code> where Ruby does not provide it, and corrects <code>Binding#caller_locations</code> argument handling.</p><a class="text-link" href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#322--2026-06-15">Read changes <span aria-hidden="true">↗</span></a></div></article>
   <article class="timeline-item" id="facets-3-2-1"><div class="timeline-date"><strong>3.2.1</strong><span>14 JUN 2026</span></div><div><h3>Core loading restored</h3><p>Repairs stale require paths that affected <code>require 'facets'</code> in 3.2.0, and adds a load-path regression check. Also adds OpenDSL and PIC.</p><a class="text-link" href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#321--2026-06-14">Read changes <span aria-hidden="true">↗</span></a></div></article>
   <article class="timeline-item" id="facets-3-2-0"><div class="timeline-date"><strong>3.2.0</strong><span>APR 2026</span></div><div><h3>Modern Ruby foundation</h3><p>Moves the minimum Ruby version to 3.1, adds methods such as <code>Array#to_ranges</code> and <code>String#dashcase</code>, and retires extensions now built into Ruby.</p><a class="text-link" href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#320--2026-04-01">Read migration notes <span aria-hidden="true">↗</span></a></div></article>
 </div></div></section>

diff --git a/docs/index.html b/docs/index.html
@@ -35,7 +35,7 @@ <h1>More of Ruby,<br><em>one method</em><br>at a time.</h1>
         <a class="button button-primary" href="learn.html">Get started <span aria-hidden="true">↗</span></a>
         <a class="button button-outline" href="https://github.com/rubyworks/facets">Explore the source <span aria-hidden="true">↗</span></a>
       </div>
-      <p class="hero-note">Version <strong>3.2.2</strong> <span aria-hidden="true">·</span> Ruby <strong>3.1+</strong> <span aria-hidden="true">·</span> BSD 2-Clause</p>
+      <p class="hero-note">Version <strong>4.0.0</strong> <span aria-hidden="true">·</span> Ruby <strong>3.1+</strong> <span aria-hidden="true">·</span> BSD 2-Clause</p>
     </div>
     <div class="hero-visual" aria-label="Ruby Facets code example">
       <div class="orbit orbit-one"></div><div class="orbit orbit-two"></div>
@@ -78,7 +78,7 @@ <h1>More of Ruby,<br><em>one method</em><br>at a time.</h1>
 </section>
 
 <section class="section release-section">
-  <div class="shell release-grid"><div><p class="kicker kicker-light">LATEST RELEASE</p><h2>Fresh facets<br>for modern Ruby.</h2><p>Version 3.2.2 includes compatibility fixes across Ruby 3.1–3.4, following the 3.2 modernization release.</p><a class="button button-light" href="news.html">Read the release notes <span aria-hidden="true">↗</span></a></div><div class="release-stamp"><span class="release-stamp-small">RUBY FACETS</span><strong>3.2.2</strong><span>JUNE 2026</span></div></div>
+  <div class="shell release-grid"><div><p class="kicker kicker-light">LATEST RELEASE</p><h2>Fresh facets<br>for modern Ruby.</h2><p>Version 4.0.0 makes <code>#try</code> strict and <code>#try!</code> lenient, adds a <code>lib/rails</code> area for Rails-compatible methods, and gives every deprecation a removal date.</p><a class="button button-light" href="news.html">Read the release notes <span aria-hidden="true">↗</span></a></div><div class="release-stamp"><span class="release-stamp-small">RUBY FACETS</span><strong>4.0.0</strong><span>SEPTEMBER 2026</span></div></div>
 </section>
 </main>
 

diff --git a/docs/learn.html b/docs/learn.html
@@ -27,7 +27,7 @@
 
   <main id="main"><section class="page-hero"><div class="shell"><p class="eyebrow"><span class="eyebrow-line"></span> THE GUIDE</p><h1>Find your way<br><em>into Facets.</em></h1><p>Install the gem, choose how much to load, and make Ruby feel a little more like yours.</p></div></section>
 <section class="section section-light"><div class="shell guide-grid"><aside class="guide-aside"><p class="kicker">ON THIS PAGE</p><a href="#install">Install</a><a href="#load">Load extensions</a><a href="#examples">Try a few methods</a><a href="#reference">Find the API</a></aside><div class="guide-content">
-  <section id="install" class="guide-block"><p class="kicker">01 / GET READY</p><h2>Install Facets</h2><p>Facets 3.2.2 requires Ruby 3.1 or newer. Install it directly with RubyGems or add it to a Bundler project.</p><div class="snippet"><div class="snippet-label">TERMINAL</div><pre><code>gem install facets</code></pre></div><div class="snippet"><div class="snippet-label">GEMFILE</div><pre><code>gem 'facets', require: false</code></pre></div><p><code>require: false</code> keeps Bundler from loading the entire core collection automatically, so you can choose the files your project needs.</p></section>
+  <section id="install" class="guide-block"><p class="kicker">01 / GET READY</p><h2>Install Facets</h2><p>Facets 4.0.0 requires Ruby 3.1 or newer. Install it directly with RubyGems or add it to a Bundler project.</p><div class="snippet"><div class="snippet-label">TERMINAL</div><pre><code>gem install facets</code></pre></div><div class="snippet"><div class="snippet-label">GEMFILE</div><pre><code>gem 'facets', require: false</code></pre></div><p><code>require: false</code> keeps Bundler from loading the entire core collection automatically, so you can choose the files your project needs.</p></section>
   <section id="load" class="guide-block"><p class="kicker">02 / CHOOSE YOUR SCOPE</p><h2>Load what fits</h2><p>Most core extension methods are stored in individual files. You can require one method, a class's core methods, or the core collection.</p><div class="snippet"><div class="snippet-label">RUBY</div><pre><code><span class="code-comment"># One method</span>
 require 'facets/array/to_ranges'
 

diff --git a/docs/news.html b/docs/news.html
@@ -26,8 +26,9 @@
   </header>
 
   <main id="main"><section class="page-hero"><div class="shell"><p class="eyebrow"><span class="eyebrow-line"></span> RELEASES & HISTORY</p><h1>A living Ruby<br><em>collection.</em></h1><p>Facets has been growing since 2004. Here are the recent releases and a path back through its story.</p></div></section>
-<section class="section section-light"><div class="shell"><div class="section-heading narrow"><p class="kicker">LATEST RELEASES</p><h2>Facets 3.2</h2><p>The 3.2 series brings the library forward for Ruby 3.1 and newer. Work merged since 3.2.2 is listed under <a href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#unreleased">Unreleased</a> in the release history.</p></div><div class="timeline">
-  <article class="timeline-item" id="facets-3-2-2"><div class="timeline-date"><strong>3.2.2</strong><span>15 JUN 2026</span></div><div><p class="tag">LATEST</p><h3>Compatibility, polished</h3><p>Fixes range intersection on Ruby 3.1 and 3.2, restores <code>Range#overlap?</code> where Ruby does not provide it, and corrects <code>Binding#caller_locations</code> argument handling.</p><a class="text-link" href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#322--2026-06-15">Read changes <span aria-hidden="true">↗</span></a></div></article>
+<section class="section section-light"><div class="shell"><div class="section-heading narrow"><p class="kicker">LATEST RELEASES</p><h2>Facets 4.0</h2><p>Facets 4.0 continues the modernization begun in 3.2 for Ruby 3.1 and newer. The 3.2.0 release changed enough that it should have been 4.0.0; 4.0.0 makes the next round of changes under the right number.</p></div><div class="timeline">
+  <article class="timeline-item" id="facets-4-0-0"><div class="timeline-date"><strong>4.0.0</strong><span>27 SEP 2026</span></div><div><p class="tag">LATEST</p><h3>Clearer by design</h3><p>Makes <code>#try</code> strict and <code>#try!</code> lenient, moves Rails-compatible methods to a new <code>lib/rails</code> area, and schedules every deprecation for removal after 2027-09-30.</p><a class="text-link" href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#400--2026-09-27">Read changes <span aria-hidden="true">↗</span></a></div></article>
+  <article class="timeline-item" id="facets-3-2-2"><div class="timeline-date"><strong>3.2.2</strong><span>15 JUN 2026</span></div><div><h3>Compatibility, polished</h3><p>Fixes range intersection on Ruby 3.1 and 3.2, restores <code>Range#overlap?</code> where Ruby does not provide it, and corrects <code>Binding#caller_locations</code> argument handling.</p><a class="text-link" href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#322--2026-06-15">Read changes <span aria-hidden="true">↗</span></a></div></article>
   <article class="timeline-item" id="facets-3-2-1"><div class="timeline-date"><strong>3.2.1</strong><span>14 JUN 2026</span></div><div><h3>Core loading restored</h3><p>Repairs stale require paths that affected <code>require 'facets'</code> in 3.2.0, and adds a load-path regression check. Also adds OpenDSL and PIC.</p><a class="text-link" href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#321--2026-06-14">Read changes <span aria-hidden="true">↗</span></a></div></article>
   <article class="timeline-item" id="facets-3-2-0"><div class="timeline-date"><strong>3.2.0</strong><span>APR 2026</span></div><div><h3>Modern Ruby foundation</h3><p>Moves the minimum Ruby version to 3.1, adds methods such as <code>Array#to_ranges</code> and <code>String#dashcase</code>, and retires extensions now built into Ruby.</p><a class="text-link" href="https://github.com/rubyworks/facets/blob/main/HISTORY.md#320--2026-04-01">Read migration notes <span aria-hidden="true">↗</span></a></div></article>
 </div></div></section>

diff --git a/lib/core/facets/version.rb b/lib/core/facets/version.rb
@@ -1,3 +1,3 @@
 module Facets
-  VERSION = '3.2.2'
+  VERSION = '4.0.0'
 end