CONTRIBUTING.md

Contributing to rescript-urql

Thank you so much for contributing to rescript-urql! We're excited you want to help make this project better with us.

rescript-urql follows the all contributors spec. We believe firmly that the whole community is vital to our success, not just those who contribute code. The best way to get involved is to start by familiarizing yourself with the urql API and getting familiar with the basics of ReScript.

How do I contribute?

We're always open to new issues and pull requests. For issues, we'll do our best to help spec out new features or bug fixes with you. We'll also tag issues to make them easier to identify as you get familiar with things. For pull requests, we're interested in all of it – new features, bug fixes, tests, docs, even the smallest typo!

If you do open a pull request for a new feature or bug, please consider adding tests in the __tests__ directory. If your pull request fixes an issue, please list the issue number in the title or refer to it in the body of the description.

How do I set up the project?

This is pretty standard. Clone the repo locally:

git clone https://github.com/FormidableLabs/rescript-urql.git

and install the dependencies:

cd rescript-urql
yarn

We really recommend having an editor plugin to run the ReScript language server. For VSCode users, rescript-vscode is the best option.

Compiling the Source

To compile the source and watch for changes:

yarn start

To build the source:

yarn build

To clean out any build artifacts:

yarn clean

Running the Demo

To run the demo, simply invoke the start:demo script:

yarn start:demo

It's often best to compile the source in watch mode (yarn start) and run the start:demo script in a separate terminal so you can get the full live reloading experience.

Running Tests

To run all test suites:

yarn test

We use bs-jest to compile and run our tests. You can pass standard Jest CLI options to this command if you want to do something particular, like run in watch mode:

yarn test --watch

or target a specific test:

yarn test -t 'should instantiate a client instance'

To get coverage statistics:

yarn coverage

Formatting

Formatting will be handled automatically for you by rescript-vscode. If you're using a different editor than VSCode, check out the official ReScript plugins for your editor of choice.

Publishing

Prior to publishing to npm, please consider drafting a release. We like to follow the format outlined by Keep a Changelog. To draft a release, add a new entry to CHANGELOG.md. Commit this change in a separate commit following the format:

git commit -m "Prepare vX.X.X release."
git push origin main

Publishing to NPM

Once you've added the CHANGELOG update and pushed the commit, you're ready to publish. We follow a pretty standard workflow using semantic versioning. Make sure you are on latest main before publishing.

git pull origin main

# Assuming you have latest main...
yarn version --<major | minor | patch>
yarn publish
git push && git push --tags

Once the release is published, make sure you copy the CHANGELOG update to the formal Releases page.