Development

So, you want to hack on GraphQL Ruby! Here are some tips for getting started.

Setup

Get your own copy of graphql-ruby by forking rmosolgo/graphql-ruby on GitHub and cloning your fork.

Then, install the dependencies:

Running the Tests

Unit tests

You can run the tests with

bundle exec rake        # tests & Rubocop
bundle exec rake test   # tests only

You can run a specific file with TEST=:

bundle exec rake test TEST=spec/graphql/query_spec.rb
# run tests in `query_spec.rb` only

You can focus on a specific example with focus:

focus
it "does something cool" do
  # ...
end

Then, only focused tests will run:

bundle exec rake test
# only the focused test will be run

(This is provided by minitest-focus.)

Integration tests

You need to pick a specific gemfile from gemfiles/ to run integration tests. For example:

BUNDLE_GEMFILE=gemfiles/rails_6.1.gemfile bundle install
BUNDLE_GEMFILE=gemfiles/rails_6.1.gemfile bundle exec rake test TEST=spec/integration/rails/graphql/relay/array_connection_spec.rb

GraphQL-CParser tests

To test the graphql_cparser gem, you have to build the binary first:

bundle exec rake build_ext

Then, run the test suite with GRAPHQL_CPARSER=1:

GRAPHQL_CPARSER=1 bundle exec rake test

(Add TEST= to pick a certain file.)

Other tests

There are system tests for checking ActionCable behavior, use:

bundle exec rake test:system

And JavaScript tests:

bundle exec rake test:js

Gemfiles, Gemfiles, Gemfiles

graphql-ruby has several gemfiles to ensure support for various Rails versions. You can specify a gemfile with BUNDLE_GEMFILE, eg:

BUNDLE_GEMFILE=gemfiles/rails_5.gemfile bundle exec rake test

Debugging with Pry

pry is included with GraphQL-Ruby’s development setup to help with debugging.

To pause execution in Ruby code, add:

binding.pry

Then, the program will pause and your terminal will become a Ruby REPL. Feel free to use pry in your development process!

Running the Benchmarks

This project includes some Rake tasks to record benchmarks:

$ bundle exec rake -T | grep bench:
rake bench:profile         # Generate a profile of the introspection query
rake bench:query           # Benchmark the introspection query
rake bench:validate        # Benchmark validation of several queries

You can save results by sending the output into a file:

$ bundle exec rake bench:validate > before.txt
$ cat before.txt
# ...
# --> benchmark output here

If you want to check performance, create a baseline by running these tasks before your changes. Then, make your changes and run the tasks again and compare your results.

Keep these points in mind when using benchmarks:

Coding Guidelines

GraphQL-Ruby uses a thorough test suite to make sure things work reliably day-after-day. Please include tests that describe your changes, for example:

Don’t fret about coding style or organization. There’s a minimal Rubocop config in .rubocop.yml which runs during CI. You can run it manually with bundle exec rake rubocop.

Website

To update the website, update the .md files in guides/.

Install the optional documentation dependencies and build the site locally:

BUNDLE_WITH=docs bundle install
bundle exec rake docs:build
bundle exec rake docs:rdoc:serve

Then visit http://127.0.0.1:8808. Run the documentation checks before submitting a change:

bundle exec rake docs:check
bundle exec rake docs:build_twice

See the documentation maintenance guide for API links, GraphQL code blocks, redirects, and release documentation.

API Docs

The GraphQL-Ruby website has a rendered version of each published gem’s API docs. Generate a local copy with:

$ bundle exec rake "docs:rdoc:build_version[1.8.0]"

The output is written to tmp/rdoc-api/1.8.0/; the release workflow publishes it under /api-doc/1.8.0/ while preserving older versions.

Versioning

GraphQL-Ruby does not attempt to deliver “semantic versioning” for the reasons described in jashkenas‘ s post, “Why Semantic Versioning Isn’t”. Instead, the following scheme is used as a guideline:

This policy is inspired by the Ruby 2.1.0+ version policy.

Pull requests and issues may be tagged with a GitHub milestone to denote when they’ll be released.

The changelog should always contain accurate and thorough information so that users can upgrade. If you have trouble upgrading based on the changelog, please open an issue on GitHub.

Releasing

GraphQL-Ruby doesn’t have a strict release schedule. If you think it should, consider opening an issue to share your thoughts.

To cut a release: