Flesh out CONTRIBUTING.md.

- Rename `run_most_specs` -> `run_specs`.
- Rename `Gemfile-custom.sample` -> `Gemfile-custom.example`.

.github/workflows/ci.yaml

@@ -39,7 +39,7 @@ jobs:
           - build_part: "run_misc_checks"
             ruby: "3.3"
             datastore: "elasticsearch:8.15.3"
-          - build_part: "run_most_specs_with_vcr"
+          - build_part: "run_specs_with_vcr"
             ruby: "3.3"
             datastore: "elasticsearch:8.15.3"
           - build_part: "run_specs_file_by_file"

CONTRIBUTING.md

@@ -43,6 +43,70 @@ Once you have Ruby installed, install the development dependencies by running `b
 This project uses Docker Engine and Docker Compose to run Elasticsearch and OpenSearch locally. We recommend installing
 [Docker Desktop](https://docs.docker.com/desktop/) to get both Docker dependencies.
 
+## Customizing the Development Environment
+
+Additional gems can be included in the bundle by defining `Gemfile-custom`.
+See [Gemfile-custom.example](Gemfile-custom.example) for an example.
+
+## Build Scripts and Executables
+
+The codebase includes a variety of build scripts and executables which are useful for local development:
+
+* `script/quick_build`: Performs an abridged version of the CI build. This is generally the most complete CI build we run locally.
+* `script/type_check`: Runs a [steep](https://github.com/soutaro/steep) type check.
+* `script/spellcheck`: Spellchecks the codebase using [codespell](https://github.com/codespell-project/codespell).
+* `script/run_specs`: Runs the test suite.
+* `script/run_gem_specs [gem_name]`: Runs the test suite for one ElasticGraph gem.
+
+### Running Tests
+
+We use [RSpec](https://rspec.info/) as our test framework.
+
+Each of the ElasticGraph gems has its own test suite in `spec` (e.g. `elasticgraph-support/spec` contains the tests for
+`elasticgraph-support`).
+
+Run the entire suite:
+
+```bash
+script/run_specs
+```
+
+To test a single gem (e.g., `elasticgraph-support`):
+
+```bash
+# From the root:
+bundle exec rspec elasticgraph-support/spec
+
+# Alternatively run a gem's specs within the context of that gem's bundle, with code coverage tracked:
+script/run_gem_specs elasticgraph-support
+
+# Alternatively, you can run tests within a subdirectory:
+cd elasticgraph-support
+bundle exec rspec
+```
+
+The RSpec CLI is extremely flexible. Here are some useful options:
+
+```bash
+# See RSpec CLI options
+bundle exec rspec --help
+
+# Run all specs in one directory
+bundle exec rspec path/to/dir
+
+# Run all specs in one file
+bundle exec rspec path/to/dir/file_spec.rb
+
+# Run the spec defined at a specific line in a file
+bundle exec rspec path/to/dir/file_spec.rb:47
+
+# Run only the tests that failed the last time they ran
+bundle exec rspec --only-failures
+
+# Run just failures, and halt after the first failure (designed to be run repeatedly)
+bundle exec rspec --next-failure
+```
+
 ---
 
 ## Communications

script/ci_parts/run_most_specs_with_vcr → script/ci_parts/run_specs_with_vcr

@@ -11,4 +11,4 @@ unset NO_VCR
 unset RUBYOPT
 
 # In addition, we want to run the extra GraphQL schema validation when running the whole schema together.
-VALIDATE_GRAPHQL_SCHEMAS=1 script/run_most_specs
+VALIDATE_GRAPHQL_SCHEMAS=1 script/run_specs

script/quick_build

@@ -34,7 +34,7 @@ bundle exec standardrb
 script/type_check
 
 bundle exec rake schema_artifacts:check
-COVERAGE=1 script/run_most_specs --backtrace
+COVERAGE=1 script/run_specs --backtrace
 
 bundle exec rake site:validate
 

script/update_ci_yaml

@@ -121,7 +121,7 @@ jobs:
           - build_part: "run_misc_checks"
             ruby: "3.3"
             datastore: "<%= primary_datastore_version %>"
-          - build_part: "run_most_specs_with_vcr"
+          - build_part: "run_specs_with_vcr"
             ruby: "3.3"
             datastore: "<%= primary_datastore_version %>"
           - build_part: "run_specs_file_by_file"

spec_support/lib/elastic_graph/spec_support/enable_simplecov.rb

@@ -96,7 +96,7 @@ def wait_for_other_processes
 
   add_filter "/bundle"
 
-  # When we use `script/run_most_specs` we avoid running the `elasticgraph-local` specs, but some of the
+  # When we use `script/run_specs` we avoid running the `elasticgraph-local` specs, but some of the
   # elasticgraph-local code gets loaded and used as a dependency. We don't want to consider its coverage
   # status if we're not running it's test suite.
   add_filter "/elasticgraph-local/" unless spec_files_to_run.any? { |f| f.include?("/elasticgraph-local/") }