MONGOID-5916 Deprecate the parameterless-not syntax

[jamis]

Summary

Mongoid has historically supported the use of not in queries, without an argument. It effectively negates everything that comes after it:

Person.not.where(name: 'Bob')

This syntax is ambiguous and results in confusing situations, so we've deprecated that syntax. It will be removed in a future major release of Mongoid.

Moving forward, please prefer passing an argument to #not, which will be negated. This can be a Hash of conditions:

Person.not(name: 'Bob')

Or, it can even be a Criteria instance directly:

Person.not(Person.where(name: 'Bob'))

This even works with named scopes.

[Copilot]

Pull request overview

This PR deprecates the parameterless Criteria#not syntax (where not negates the following query operations) and updates related specs and deprecation plumbing so legacy behavior can continue to be tested while emitting (or silencing) deprecation warnings.

Changes:

• Add a deprecation warning when Selectable#not is called with no arguments.
• Introduce a shared deprecator + deprecation warning helper with “warn once” guarding (plus a test reset hook).
• Update timeless and criteria specs to use block-based timeless and to silence deprecations where deprecated not syntax is exercised.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lib/mongoid/criteria/queryable/selectable.rb	Emits a deprecation warning for #not when called without arguments; updates method docs/examples.
lib/mongoid/deprecable.rb	Adds Mongoid.deprecator, Mongoid.deprecation_warning, and a guarded “warn once” mechanism + test reset.
lib/mongoid/timestamps/timeless.rb	Switches timeless block-less deprecation to the shared Mongoid.deprecation_warning API with callsite adjustment.
spec/mongoid/criteria/queryable/selectable_logical_spec.rb	Silences deprecations in specs that validate deprecated parameterless-not behavior.
spec/mongoid/timestamps/timeless_spec.rb	Updates tests to use block-form timeless and resets deprecation-warning state for deterministic assertions.

Comments suppressed due to low confidence (1)

spec/mongoid/timestamps/timeless_spec.rb:68

• This example description says the parent is created "with a timestamp" but the expectation asserts created_at is nil (i.e. no timestamp). Updating the description will make the spec intention clearer.

          Chicken.timeless { Chicken.create! }
        end

        it 'creates the parent with a timestamp' do
          expect(chicken.created_at).to be_nil
        end

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.