Thank you for reading this, all contributions, issues and feature requests are always very welcome.
The project is currently organized as a NPM workspace with 3 packages:
graphql-markdown
is the NodeJS engine for generating Markdown from a GraphQL schema using ETA template engine for layouts,graphql-markdown-cli
is the command line tool allowing to usegraphql-markdown
from the shell,docusaurus2-graphql-doc-generator
is the implementation ofgraphql-markdown
for Docusaurus using custom layouts.
Some useful resources:
GraphQL Config
is the configuration library,GraphQL Tools
is used for loading GraphQL schema from various sources,ETA
is the template engine for rendering content,Jest
is the testing framework for all type of tests.
I am trying to keep a high level of testing using Jest and Stryker. If you submit a code contributions, then please ensure that you have added or updated required tests.
All tests are included in the GitHub action workflows and executed on every push. The exception are the mutation tests executed only when pushing code to the main
branch.
If you spot some missing tests, or improvements, we will gladly accept a pull request, for which we will love you forever as we can always use better test coverage.
When your change is ready, please remember to run the linter checks and tests before creating a Pull Request:
npm run lint --fix
checks that your code is a good it can be as per our ESLint conventions,npm run prettier
makes your code pretty and nice to review,npm run test
runs a bunch of tests, hopefully all pass including the ones you might have added or updated,npm run test:e2e
runs the end-to-end test suite, this is especially useful for major changes,npm run test:stryker
(optional) runs the mutation tests, you should run it if you want to improve the tests (always good to run once, but it can take up to 15 minutes).
Please send a GitHub Pull Request with a clear list of what you've done (read more about pull requests).
Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:
$ git commit -m "A brief summary of the commit
>
> A paragraph describing what changed and its impact."
Read the project code and get familiar with the style. If you feel something can be done in a better way, then your suggestion will be welcome.
Most of the coding conventions are included into the EditorConfig file .editorconfig
, and in the ESLint set of rules .eslintrc.cjs
. This way, your IDE will provides you all necessary guidance.
In addition, to them, I am opinionated on the following:
- code should be atomic, i.e. your methods and functions should do only one thing, so they can do it well, and are easy to test,
- types Typescript should be defined before hand to make them easily reusable, including in tests
- tests should be atomic, i.e. avoid one test fits all, mocking is always welcome,
- errors and edges cases exists, users will always go beyond the intended design and the GraphQL specification is evolving, so remember to handle them and to test them,
- external dependencies should be avoided, and cost versus benefits should be documented in the pull request if a dependency is added.
Last, but not least, please do not use --no-verify
when pushing code.
Thanks, Gregory Heitz (@edno)