Contributing to graphql-js
We want to make contributing to this project as easy and transparent as possible. Hopefully this document makes the process for contributing clear and answers any questions you may have.
Issues
We use GitHub issues to track public bugs and requests. Please ensure your bug description is clear and has sufficient instructions to be able to reproduce the issue. The absolute best way to do that is to add a failing test to our test suite via a pull request, but a reduced test case on a site like StackBlitz or CodeSandbox is also very helpful.
Pull Requests
All active development of graphql-js happens on GitHub. We actively welcome your pull requests.
Considered Changes
Since graphql-js is a reference implementation of the GraphQL spec, only changes which comply with this spec will be considered. If you have a change in mind which requires a change to the spec, please consider opening an issue against the spec and/or attending a GraphQL Working Group meeting to discuss your proposed change. See the contribution guide of the specification for further information. Stage 1 and 2 proposals may be implemented within graphql-js behind a feature flag.
GraphQL Specification Membership Agreement
This repository is managed by EasyCLA. Project participants must sign the free GraphQL Specification Membership agreement before making a contribution. You only need to do this one time, and it can be signed by individual contributors or their employers.
To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a membership agreement from you.
You can find detailed information here. If you have issues, please email operations@graphql.org.
If your company benefits from GraphQL and you would like to provide essential financial support for the systems and people that power our community, please also consider membership in the GraphQL Foundation.
Getting Started
-
Fork this repo by using the "Fork" button in the upper-right
-
Check out your fork
git clone git@github.com:your_name_here/graphql-js.git -
Install or Update all dependencies
npm install -
Get coding! If you've added code, add tests. If you've changed APIs, update any relevant documentation or tests. Ensure your work is committed within a feature branch.
-
Ensure all tests pass
npm test
Coding Style
This project uses Prettier for standard formatting. To
ensure your pull request matches the style guides, run npm run prettier.
- 2 spaces for indentation (no tabs)
- 80 character line length strongly preferred.
- Prefer
'over" - ES6 syntax when possible. However do not rely on ES6-specific functions to be available.
- Use TypeScript.
- Use semicolons;
- Trailing commas,
- Avd abbr wrds.
Documentation
The documentation website is published from the 17.x.x branch. Website source
lives under website/, with general guides in website/pages/docs and upgrade
guides in website/pages/upgrade-guides.
The API reference pages under website/pages/api-v*/ are generated during
website builds and are not committed. The build uses the working tree for the
current major and fetches the other documented release branches. Updates to
those branches appear on the next website deployment. The production build
includes the generated pages in website/out; the existing website deployment
publishes that output. The build does not commit or push generated source files
back to the release branches.
Install dependencies and build from the website package:
cd website
npm ci --ignore-scripts
npm run build
Use npm run dev instead of npm run build to start the development server.
Both commands generate API docs first and require network access.
To generate API pages separately from website/, specify one or more source refs:
npm run generate:docs -- local
Each argument is either local or a local git ref such as a branch, tag, SHA,
or HEAD. For git refs, the generator creates detached temporary worktrees. For
local, it snapshots the current working tree, including uncommitted changes.
The generator infers the major version from each source's package.json, writes
the corresponding api-v* output directory, and fails if more than one input
resolves to the same major version.
Executable API examples
Run npm run check:examples to execute JSDoc @example code fences in src
against the built npm package. CI runs the same check on the latest supported
Node.js version.
Executable examples must use TypeScript, with a ts or typescript fence.
Each fence is a separate ES module: include its imports and setup. All examples
are type checked against the built package before execution, using the
repository's TypeScript settings except noUnusedLocals. Examples must both
type check and run successfully. Use optional chaining for optional values or
assert to check and narrow required values, rather than non-null assertions.
Only graphql and gql fences are excluded from execution. Examples without
expectations are still type checked and run as smoke tests.
Add a fenced example under @example in the API's JSDoc comment. Use trailing
comments to describe expected results:
/**
* Parses a GraphQL document.
* @example
* ```ts
* import { parse } from 'graphql';
*
* parse('{ hello }').kind; // => 'Document'
* parse('invalid'); // throws an error
* parse('{ hello }'); // does not throw
* ```
*/
Annotations can follow an expression statement or a variable declaration.
On a declaration, // => compares the initializer's result and the variable
keeps that value:
import { parse } from 'graphql';
const kind = parse('{ hello }').kind; // => 'Document'
kind.toLowerCase(); // => 'document'
Use one initialized variable declaration per annotation. Destructuring checks the
whole initializer's result before assigning its properties to the variables.
When an initializer is expected to throw, its variables are left undefined.
Top-level await is supported. Inside an example fence, an async result can be
checked like this:
import { buildSchema, graphql } from 'graphql';
const schema = buildSchema('type Query { hello: String }');
const result = await graphql({
schema,
source: '{ hello }',
rootValue: { hello: () => 'world' },
});
result; // => { data: { hello: 'world' } }
For an expected promise rejection, use
await Promise.reject(new Error('expected')); // throws an error.
Keep the expected expression on the same line as // =>. For a multiline value,
define a variable and reference it in the expectation:
import { buildSchema, printSchema } from 'graphql';
const schema = buildSchema('type Query { hello: String }');
const expected = `type Query {
hello: String
}`;
printSchema(schema); // => expected
Comparisons use the existing expectJSON test helper. It calls toJSON methods
and compares object properties, including GraphQL's null-prototype dictionaries.
Missing properties and properties set to undefined remain distinct.
Assertions can appear inside callbacks, functions, loops, and conditional blocks. Every annotated expression must execute at least once before the example finishes:
import { parse, visit } from 'graphql';
visit(parse('{ greeting }'), {
Field(node) {
node.name.value; // => 'greeting'
},
});
An uncalled callback or a skipped branch containing an assertion fails the check. Await asynchronous work so its assertions run before the example finishes. Repeated calls to one assertion do not compensate for another that never runs.
Invalid annotations and unexpected errors fail the check, with the example's source file and line in the output. Examples run sequentially and share GraphQL module state. They should not interfere with one another.
Review and Merge Process
- Pull requests are required to pass all tests and checks before they can be merged.
- Ideally, pull requests should be reviewed by at least two members of the
@graphql/graphql-js-reviewersteam before they are merged, preferably from separate organizations. For more complex pull requests, a larger cohort of reviewers is suggested. - Any reviewer may request that the topic be brought for more in depth discussion at a GraphQL JS Working Group meeting, where decisions will be made by consensus.
- A PR that has been merged without discussion at a GraphQL JS Working Group meeting can be revisited in any subsequent meeting; the PR may be reverted as a result of that discussion.
Discussion
Feel free to reach out via the graphql-js channel on the official Discord server to discuss issues, pull requests, or anything graphql-js related.
Release on NPM
Releases on maintained release branches are managed by local scripts and GitHub Actions:
git switch 17.x.x
git switch -c <my_release_branch>
export GH_TOKEN=<token> # required to build changelog via GitHub API requests
Prepare a stable release:
npm run release:prepare -- 17.x.x patch
Or, prepare a beta prerelease:
npm run release:prepare -- 17.x.x prerelease --preid beta
Or, prepare an rc prerelease:
npm run release:prepare -- 17.x.x prerelease --preid rc
When --preid is provided, the release script uses it as the npm publish tag.
Without a prerelease preid, stable releases from the latest major use the npm
latest tag and are marked as the latest GitHub release. Stable releases from
older maintained majors use an npm latest-<major> tag and are explicitly not
marked as the latest GitHub release. Users can install those older majors with a
semver specifier, for example npm install graphql@16.
Push <my_release_branch>, open a PR from <my_release_branch> to the target
release branch, wait for CI to pass, merge the PR, and then approve the GitHub
Actions release workflow.
License
By contributing to graphql-js, you agree that your contributions will be licensed under its MIT license.