The PostGraphile project welcomes all contributors, we want to invest in you so you can invest back into PostGraphile. Together we can make great software that enables developers to build powerful applications in much less time then would previously have been taken. This document aims to help you get started contributing to the project.
First of all, our development environment is focussed around Unix tools. If you are on Windows, you may need to use something like Docker or a VM to help you develop.
Since PostGraphile is mostly powered by Graphile Engine the best way to develop it is to do it in the context of a Graphile Engine build so that you may dig into the depths if you need to.
We use yarn workspaces, so it's very important that you use the
package manager rather an npm whilst developing PostGraphile.
npm install -g yarn
Before we start, check that you're running up to date versions of the relevant tools, you should be running at least:
$ node --version v10.13.0 $ yarn --version 1.12.1 $ git --version git version 2.18.0 $ watchman --version # optional 4.9.0
(If you don't have
watchman that's fine, but it helps when watching large
numbers of files. On Mac you can install it using homebrew:
brew install watchman)
To get started, we're going to check out
graphile-engine, and then we're
going to check out
postgraphile inside of
graphile-engine. With a few
tweaks this will enable
postgraphile to use the development version of the
graphile-engine without needing to perform
yarn link etc.
It should be safe to copy and paste these commands into your terminal (one at a time), but if you're using zsh you may want to run this first so that comments are ignored:
Okay, here's the setup:
# Clone graphile-engine: git clone firstname.lastname@example.org:graphile/graphile-engine.git graphile-engine # Clone postgraphile _inside of_ graphile-engine: git clone email@example.com:graphile/postgraphile.git graphile-engine/postgraphile ######################################## # Initial setup for graphile-engine cd graphile-engine # Install deps: yarn # Monorepo stuff: yarn lerna bootstrap # Run initial build: yarn prepack:all ######################################## # Initial setup for postgraphile cd postgraphile # Install deps: yarn # Remove deps that should be served by the parent graphile-engine: ./rmlocal.sh # Builds GraphiQL, images, etc so they can be require()d: yarn make-assets
Graphile Engine is built in a mixture of TypeScript and Flow (we're slowly
migrating to TypeScript); which means it has a compile step. For developer
productivity we don't incur this compilation cost every time we run the
development version of PostGraphile, instead we require the compiled code in
most places. This means that we must watch the source code for changes so
that when we run the compiled code it's not out of date. To do this, in the
root of graphile-engine, run
This will compile everything, and then monitor for changes and compile just the changed files. Every time a file is compiled it will be listed in the output - be careful to check for errors!
You should leave this watch process running, so open another terminal to do further work.
First, change into the postgraphile directory (
To run PostGraphile in development, you can use the
This command emulates the
postgraphile command, and it has two modes. If
you want the
scripts/dev command to exit when
postgraphile would, add two
# Will run once and exit on error or `-X` option scripts/dev -- -c postgres://localhost/my_db -s my_schema --watch --enhance-graphiql
scripts/dev act more like a regular build - i.e. exiting on
-X commands or when an error occurs.
If, however, you want
scripts/dev to automatically restart whenever you
change the PostGraphile or Graphile Engine source code, run it without the
--. To manually restart the server type in
rs and hit enter while
scripts/dev is running.
# Will monitor the source for changes and restart automatically scripts/dev -c postgres://localhost/my_db -s my_schema --watch --enhance-graphiql
Updating or changing branches
Due to this peculiar setup, when you want to update or switch branches, you have to do an extra couple steps than you might expect.
Thanks to yarn workspaces, updating the
git pull --rebase # or checkout a branch, or whatever yarn # update deps
If you're running
yarn watch in the
graphile-engine folder then it's
probably a good idea to restart it incase any of the dependencies have
git pull --rebase # or checkout a branch, or whatever yarn # update deps ./rmlocal.sh # Remove deps that should be served by the parent graphile-engine
./rmlocal.sh script is the one you must remember to run again -
otherwise yarn will restore the release versions of
graphile-build, thus your local changes won't be represented.
PostGraphile uses Jest for testing to take
advantage of Jest’s snapshot feature. We test against a local database, so
make sure PostgreSQL is running on
Graphile Engine uses a user-configurable test database. For historic reasons,
Benjie calls it
pggql_test (this is from before Graphile Engine had a
name!), so we'll use that name here:
We must then export a
TEST_DATABASE_URL environment variable so the tests
know where to install. WARNING: this database will be overwritten!
Then you can run the tests with
This takes a while; I'd advise that you focus on the integration tests in
postgraphile-core in most cases; and since we're using jest you can pass a
filter such as
queries to only run tests with a file name that contains the
cd packages/postgraphile-core yarn test queries
To run PostGraphile tests you will need to first create the
Then run the test suite with:
When developing PostGraphile, we recommend using the Jest watch mode feature. So instead you would run tests like so:
yarn test --watch
(If you get an error about too many open files, consider installing
watchman as mentioned above.)
Now, only the tests in the files you have changed will be run. There are some slow tests in the PostGraphile suite so hopefully this should make your development time faster. Once you are in watch mode, Jest will present you with some options you can use to better configure your testing experience.
We make use of the Jest snapshot feature. Even when you change small things
the snapshot tests are likely to fail, this is expected. To update the
snapshots so that the tests pass again, you can press
u if you're running
in watch mode, or you can run
yarn test -u. You should carefully review the
changes to the snapshots to ensure they're what you intended. Commit the
changes to the snapshots and the changed snapshots will be reviewed along
with the rest of your changes in the PR review process.
The instance of GraphiQL used by PostGraphile is a
postgraphiql. When developing PostGraphile (running
scripts/dev only), GraphiQL will run on a different port to take advantage
create-react-app developer experience.
postgraphiql has it's own
it depends on a specific version of GraphQL which is different from the wide
range supported by PostGraphile/Graphile Engine. When we build PostGraphile
before publishing (with
scripts/build), GraphiQL is built into a resources
served by the PostGraphile middleware people import into their projects.
PostGraphile team use
messages: a type (
docs/etc.), a scope
tests) and then the commit message.
Commit messages are written in the imperative tense.
Here’s a few examples:
feat(ci): run against multiple postgres versions fix(postgraphile): fix opaque error messages chore(docs): rename anonymous role to default role
When committing to a branch or a PR you do not need to adhere to this format.
However, all commits to the
master branch must be in this format. Often all
of the commits in a PR will be squashed and a commit message of this format
will be written to summarize the changes.
You must use one of the following types:
Common scopes are as follows. You are not required to use any of the following scopes and may instead invent your own. These are just a few that get commonly used.
Here are some resources that will help you learn more about Postgres and GraphQL so that you may understand more of what is going on inside PostGraphile.
- The Anatomy of a GraphQL Query. This article provides the vocabulary you need to talk about a GraphQL query technically.