From 3ad0efa03fce8dc81f522254fcc68eb591902d2e Mon Sep 17 00:00:00 2001
From: Daniel Arnold <darnold8@gmail.com>
Date: Sat, 4 Oct 2025 17:19:35 -0400
Subject: [PATCH 1/2] update readme

---
 README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 65 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 97f01d2..04f8ecf 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,11 @@
-Mongoid::Includes
-=====================
+# Mongoid::Includes
 
 [![Gem Version](https://badge.fury.io/rb/mongoid_includes.svg)](https://rubygems.org/gems/mongoid_includes)
 [![Build Status](https://github.com/cacheventures/mongoid_includes/workflows/CI/badge.svg)](https://github.com/cacheventures/mongoid_includes/actions)
 
 `Mongoid::Includes` improves eager loading in Mongoid, supporting polymorphic associations, and nested eager loading.
 
-### Usage
+## Usage
 
 ```ruby
 Album.includes(:songs).includes(:musicians, from: :band)
@@ -19,8 +18,10 @@ released_only = ->(albums) { albums.where(released: true) }
 Musician.includes(:band, with: ->(bands) { bands.limit(2).includes(:albums, with: released_only) })
 ```
 
-### Pro Tip
+## Pro Tip
+
 Since you can modify the queries for the associations, you can use `only` and make your queries even faster:
+
 ```ruby
 Band.includes :musicians, with: ->(musicians) { musicians.only(:id, :name) }
 ```
@@ -36,10 +37,10 @@ Band.includes :musicians, with: ->(musicians) { musicians.only(:id, :name) }
 Add this line to your application's Gemfile and run `bundle install`:
 
 ```ruby
-  gem 'mongoid_includes'
+gem 'mongoid_includes'
 ```
 
-Or install it yourself running:
+Or install it yourself by running:
 
 ```sh
 gem install mongoid_includes
@@ -48,3 +49,61 @@ gem install mongoid_includes
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Running tests
+
+To run the full test suite locally:
+
+```sh
+bundle install
+bundle exec rspec
+# or use the bundled binary
+bin/rspec
+```
+
+To run the tests against the Mongoid 8 matrix (this project provides a separate Gemfile at `gemfiles/mongoid8.gemfile`), set `BUNDLE_GEMFILE` to that file before installing or running the suite:
+
+```sh
+# install gems for the mongoid8 Gemfile
+BUNDLE_GEMFILE=gemfiles/mongoid8.gemfile bundle install
+
+# run the specs using that Gemfile
+BUNDLE_GEMFILE=gemfiles/mongoid8.gemfile bundle exec rspec
+# or
+BUNDLE_GEMFILE=gemfiles/mongoid8.gemfile bundle exec bin/rspec
+```
+
+If you only need to run a single spec file while using the alternate Gemfile, pass the path to `rspec` as usual, for example:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/mongoid8.gemfile bundle exec rspec spec/mongoid/includes/criteria_spec.rb
+```
+
+## Contributing
+
+Contributions are welcome. If you'd like to report a bug, suggest an improvement, or submit a patch, please follow these steps:
+
+1. Fork the repository on GitHub.
+2. Create a feature branch from `master` (or from the branch you're targeting):
+
+   ```sh
+   git switch -c my-feature-branch
+   ```
+
+3. Make your changes. Add or update tests when appropriate.
+4. Run the test suite locally to ensure everything passes:
+
+   ```sh
+   bundle install
+   bundle exec rspec
+   ```
+
+5. Commit your changes with a clear message and push your branch to your fork:
+
+   ```sh
+   git add -A
+   git commit -m "Short, descriptive message"
+   git push origin my-feature-branch
+   ```
+
+6. Open a Pull Request against the `master` branch of this repository. In your PR description, explain the problem, what you changed, and any notes about compatibility or required steps.

From ffa2cee62aa861412c8bf5bec7f2f6977b1d5780 Mon Sep 17 00:00:00 2001
From: Daniel Arnold <darnold8@gmail.com>
Date: Sat, 4 Oct 2025 17:23:59 -0400
Subject: [PATCH 2/2] fix bin/rspec

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 04f8ecf..df6452e 100644
--- a/README.md
+++ b/README.md
@@ -70,7 +70,7 @@ BUNDLE_GEMFILE=gemfiles/mongoid8.gemfile bundle install
 # run the specs using that Gemfile
 BUNDLE_GEMFILE=gemfiles/mongoid8.gemfile bundle exec rspec
 # or
-BUNDLE_GEMFILE=gemfiles/mongoid8.gemfile bundle exec bin/rspec
+BUNDLE_GEMFILE=gemfiles/mongoid8.gemfile bin/rspec
 ```
 
 If you only need to run a single spec file while using the alternate Gemfile, pass the path to `rspec` as usual, for example: