From 79d7b497c993bf6bb3a81a4cd4b3e3eae3435211 Mon Sep 17 00:00:00 2001 From: Anon Ray Date: Wed, 11 Jul 2018 10:34:29 +0000 Subject: [PATCH] add contributing guidelines for server (#104) --- CONTRIBUTING.md | 69 +++++++++++++++++++++++++++++++++++------- server/CONTRIBUTING.md | 44 ++++++++++++++++++++++++++- 2 files changed, 101 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6cd68930114..8ec08a5dda1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,67 @@ -# Contributing +# Contributing to Hasura graphql-engine -[hasura/graphql-engine](https://github.com/hasura/graphql-engine) is a mono-repo consisting of 3 components. Each have their own contributing guides: +*First*: if you're unsure or afraid of anything, just ask or submit the issue or +pull request anyway. You won't be yelled at for giving your best effort. The +worst that can happen is that you'll be politely asked to change something. We +appreciate any sort of contributions, and don't want a wall of rules to get in +the way of that. + +However, for those individuals who want a bit more guidance on the best way to +contribute to the project, read on. This document will cover what we're looking +for. By addressing all the points we're looking for, it raises the chances we +can quickly merge or address your contributions. + + +## Overview + +[hasura/graphql-engine](https://github.com/hasura/graphql-engine) is a mono-repo +consisting of 3 components. Each have their own contributing guides: 1. [Server (Haskell)](server/CONTRIBUTING.md) 2. [CLI (Go)](cli/CONTRIBUTING.md) 3. [Console (JavaScript)](console/CONTRIBUTING.md) -All of the three components have a single version, denoted by either the git tag or a combination of branch name and git commit sha. +All of the three components have a single version, denoted by either the git +tag, or a combination of branch name and git commit SHA. + +## Issues + +### Reporting an Issue + +- Make sure you test against the latest released version. It is possible we + already fixed the bug you're experiencing. + +- Also check the `CHANGELOG.md` to see if any unreleased changes affect the issue. + +- Provide steps to reproduce the issue, including Postgres version, + graphql-engine version and the provider you are running on (Heroku, Docker + etc.). + +- Please include logs of the server, if relevant. + ## Common guidelines -- Please make sure there is an issue associated with the work the work you're doing. -- If you're working on an issue, please comment that you are doing so to prevent duplicate work by others also. -- Squash your commits and refer to the issue using `fix #` or `close #` in the commit message. -- Commit messages: - - Please keep the it under 100 characters. This allows the message to be easier to read on github as well as in various git tools and produces a nice, neat commit log - - Use the imperative present tense: "change" not "changed" nor "changes" - - Don't capitalize the first letter - - Do not add a dot (.) at the end \ No newline at end of file +- Please make sure there is an issue associated with the work that you're doing. + +- If you're working on an issue, please comment that you are doing so to prevent + duplicate work by others also. + +- Squash your commits and refer to the issue using `fix #` or `close + #` in the commit message, at the end. + For example: `resolve answers to everything (fix #42)` or `resolve answers to everything, fix #42` + +## Commit messages + + - The first line should be a summary of the changes - not execeeding 50 + characters. Followed by an optional body which has more details about the + changes. (https://github.com/erlang/otp/wiki/writing-good-commit-messages) + + - Use the imperative present tense: "add/fix/change", not "added/fixed/changed" nor "adds/fixes/changes". + + - Don't capitalize the first letter of the summary line. + + - Do not add a period/dot (.) at the end in the summary line. + + +(Credits: Some sections are adapted from https://github.com/PostgREST/postgrest/blob/master/.github/CONTRIBUTING.md) diff --git a/server/CONTRIBUTING.md b/server/CONTRIBUTING.md index 0e28ebda276..5cb4a3fffe8 100644 --- a/server/CONTRIBUTING.md +++ b/server/CONTRIBUTING.md @@ -1,3 +1,45 @@ # Contributing -TODO \ No newline at end of file +This guide is for setting-up the graphql-engine server for development on your +own machine, and how to contribute. + +## Pre-requisites + +- [stack](https://docs.haskellstack.org/en/stable/README/#how-to-install) +- A postgres server (Recommended: Use docker to run a local postgres instance) +- GNU Make (optional) + +## Development workflow + +### Fork and clone +- Fork the repo on GitHub +- Clone your forked repo: `git clone https://github.com//graphql-engine` + +### Compile +- `cd graphql-engine` +- `stack build --fast` + +### Run +- Make sure postgres is running +- Create a database on postgres +- Run the binary: `stack exec graphql-engine -- --database-url=` + +### Work +- Work on the feature/fix +- Add testcases if relevant + +### Test +- Run tests: `stack test --ta --database-url=` + +### Create Pull Request +- Make sure your commit messages meet the [guidelines](../CONTRIBUTING.md). +- Create a pull request from your forked repo to the main repo. +- Every pull request will automatically build and run the tests. + +## Code conventions + +This helps enforce a uniform style for all committers. + +- Compiler warnings are turned on, make sure your code has no warnings. +- Use [hlint](https://github.com/ndmitchell/hlint) to make sure your code has no warnings. +- Use [stylish-haskell](https://github.com/jaspervdj/stylish-haskell) to format your code.