So, you want to hack on GraphQL Ruby! Here are some tips for getting started.
Get your own copy of graphql-ruby by forking
rmosolgo/graphql-ruby on GitHub and cloning your fork.
Then, install the dependencies:
brew install sqlite && brew install mongodb)
You can run the tests with
bundle exec rake # tests & Rubocop bundle exec rake test # tests only
You can run a specific file with
bundle exec rake test TEST=spec/graphql/query_spec.rb # run tests in `query_spec.rb` only
Alternatively, you can run a specific file with the m gem:
m spec/graphql/query_spec.rb # run tests in `query_spec.rb` only
You can focus on a specific example with
focus it "does something cool" do # ... end
focused tests will run:
bundle exec rake test # only the focused test will be run
(This is provided by
You can watch files with
bundle exec guard
When a file in
lib/ is modified,
guard will run the corresponding file in
spec. Guard also respects
# test_via: comments, so it will run that test when the file changes (if there is no corresponding file by name).
You need to pick a specific gemfile from gemfiles/ to run integration tests. For example:
BUNDLE_GEMFILE=gemfiles/rails_5.1.gemfile bundle install BUNDLE_GEMFILE=gemfiles/rails_5.1.gemfile bundle exec rake test TEST=spec/integration/rails/graphql/relay/array_connection_spec.rb
There are system tests for checking ActionCable behavior, use:
bundle exec rake test:system
bundle exec rake test:js
graphql-ruby has several gemfiles to ensure support for various Rails versions.
You can run all gemfiles with
You can specify a gemfile with
BUNDLE_GEMFILE=gemfiles/rails_5.gemfile bundle exec rake
pry is included with GraphQL-Ruby’s development setup to help with debugging.
To pause execution in Ruby code, add:
Then, the program will pause and your terminal will become a Ruby REPL. Feel free to use
pry in your development process!
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:
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.
The lexer and parser use a multistep build process:
.rbfiles in GraphQL-Ruby
To update the lexer or parser, you should update their corresponding definitions (
parser.y). Then, you can run
bundle exec rake build_parser to re-generate the
You will need Ragel to build the lexer (see above).
If you start guard (
bundle exec guard), the
.rb files will be rebuilt whenever the definition files are modified.
To update the website, update the
.md files in
To preview your changes, you can serve the website locally:
bundle exec rake site:serve
To publish the website with GitHub pages, run the Rake task:
bundle exec rake site:publish
GraphQL-Ruby’s search index is powered by Algolia. To update the index, you need the API key in an environment variable:
$ export ALGOLIA_API_KEY=...
Without this key, the search index will fall out-of-sync with the website. Contact @rmosolgo to gain access to this key.
The GraphQL-Ruby website has its own rendered version of the gem’s API docs. They’re pushed to GitHub pages with a special process.
First, generate local copies of the docs you want to publish:
$ bundle exec rake apidocs:gen_version[1.8.0] # for example, generate docs that you want to publish
Then, check them out locally:
$ bundle exec rake site:serve # then visit http://localhost:4000/api-doc/1.8.0/
Then, publish them as part of the whole site:
$ bundle exec rake site:publish
Finally, check your work by visiting the docs on the website.
GraphQL-Ruby does not attempt to deliver “semantic versioning” for the reasons described in
s post, “Why Semantic Versioning Isn’t”. Instead, the following scheme is used as a guideline:
PATCHversion indicates bug fixes or small features for specific use cases. Ideally, you can upgrade patch versions with only a quick skim of the changelog.
MINORversion indicates significant additions, internal refactors, or small breaking changes. When upgrading a minor version, check the changelog for any new features or breaking changes which apply to your system. The changelog will always include an upgrade path for any breaking changes. Minor versions may also include deprecation warnings to warn about upcoming breaking changes.
MAJORversion indicates significant breaking changes. Do not expect code to run without some modification, especially if the code yielded deprecation warnings.
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.
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:
CHANGELOG.mdfor the new version:
### Breaking Changesand include migration notes if possible
lib/graphql/version.rbwith the new version number
bundle exec rake release
bundle exec rake buildthen
gem push pkg/graphql-<version>.gem,
git tag v<version> && git push v<version>
bundle exec rake apidocs:gen_version[<your.version.number>]
bundle exec rake site:publish