Merge pull request #112 from input-output-hk/update-docs

Reorganisation of docs

README.md

@@ -1,15 +1,19 @@
 # Cardano GraphQL
-[![Build Status](https://jenkins.daedalus-operations.com/buildStatus/icon?job=cardano-graphql%2Fdevelop)](https://jenkins.daedalus-operations.com/blue/organizations/jenkins/cardano-graphql/)
+[![Build Status](https://jenkins.daedalus-operations.com/buildStatus/icon?job=cardano-graphql%2Fmaster)](https://jenkins.daedalus-operations.com/blue/organizations/jenkins/cardano-graphql/)
 
 Cross-platform, _typed_, and **queryable** API service for Cardano, powered by [Hasura](https://hasura.io/) to precisely query projected Cardano state from [PostgreSQL](https://www.postgresql.org/).
 
 The [schema](src_temp/schema.graphql) is defined in native `.graphql`, and used to generate [packages](src/generated_packages/README.md) for internal and client-side static typing. [Apollo Server](https://www.apollographql.com/docs/apollo-server/) exposes the NodeJS execution engine over a HTTP endpoint. 
 
+**GraphQL** is a query language and execution environment with server and client implementations across many programming languages. The language can be serialized for network transmission, schema implementations hashed for assurance, and is suited for describing most domains.
+
+**TypeScript** (and JS) has the largest pool of production-ready libraries, developers, and interoperability in the GraphQL and web ecosystem in general. TypeScript definitions for the schema is generated using [GraphQL Code Generator](https://graphql-code-generator.com), is used within this implementation and [will be made available as a package](https://github.com/input-output-hk/cardano-graphql/issues/8) for client consumption. [Other targets](https://graphql-code-generator.com/docs/plugins/) can be included in our build process for automated cross-language tooling.
+
 ## Documentation
 Integrated query UI and documentation is available in the GraphQL Playground, available at http://localhost:3100 when running `yarn start:test-stack`.
 
-- [API Consumer Documentation](./docs/api_consumer)
-- [Developer Documentation](./docs/developer)
-- [Updating Hasura Metadata](./docs/hasura)
-- [Refresh Test DB Dump](./docs/refresh_db)
+- [API Consumer](./docs/api_consumer)
+- [Developer](./docs/developer)
+- [Maintainer](./docs/maintainer)
+- [QA](./docs/qa)
 

docs/README.md

@@ -1,22 +1,5 @@
 # Documentation
  - [API Consumer](./api_consumer)
  - [Developer](./developer)
-
-**GraphQL** is a query language and execution environment with server and client implementations across many programming languages. The language can be serialized for network transmission, schema implementations hashed for assurance, and is suited for describing most domains.
-
-**TypeScript** (and JS) has the largest pool of production-ready libraries, developers, and interoperability in the GraphQL and web ecosystem in general. TypeScript definitions for the schema is generated using [GraphQL Code Generator](https://graphql-code-generator.com), is used within this implementation and [will be made available as a package](https://github.com/input-output-hk/cardano-graphql/issues/8) for client consumption. [Other targets](https://graphql-code-generator.com/docs/plugins/) can be included in our build process for automated cross-language tooling.
-
-
- ## ENVs
- ### `API_PORT`: Number
-Default: `3100`
-
-### `HASURA_URI`: String
-Hasura GraphQL server endpoint eg `http://localhost:8090/v1/graphql`
-
-## `QUERY_DEPTH_LIMIT`: Number 
-Default `10`
-Used to set [depthLimit](https://github.com/stems/graphql-depth-limit)
-
-## `TRACING`: Boolean
-Passed as an option to [ApolloServer](https://www.apollographql.com/docs/apollo-server/api/apollo-server/)
+ - [Maintainer](./maintainer)
+ - [QA](./qa)

docs/api_consumer/interacting_with_the_api.md

@@ -3,10 +3,13 @@ The API is served over TCP, leveraging the existing infrastructure of HTTP. Grap
 
 ### Command Line
 ```
-curl -X POST \
+➜  Curl -X POST \  
 -H "Content-Type: application/json" \
 -d '{"query": "{ cardano { blockHeight }}"}' \
-http://localhost:4000/graphql
+http://localhost:3100/graphql  
+
+{"data":{"cardano":{"blockHeight":70205}}}
+
 ```
 
 ### Request within app

docs/developer/README.md

@@ -1,8 +1,8 @@
 # Developer
+
+Review to level concepts in [project architecture](./architecture.md) first. [Configuration](./configuration.md) of the development environment is possible.  
 
-Review to level concepts in [project architecture](./architecture.md) first.
-
-The project uses a [GitFlow](https://danielkummer.github.io/git-flow-cheatsheet/) process, so all features and fixes must be aimed at `develop` via a Pull Request.
+The project uses the [GitLab Flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html) process, so branch from `master` for all changes.
 
 This project is setup to support a [Wallaby](https://wallabyjs.com/) integrated development experience, or test run on file save TDD workflow. You run **one** of the following yarn scripts running during development: 
 
@@ -19,4 +19,3 @@ Services and a [ts-node-dev](https://www.npmjs.com/package/ts-node-dev) watcher
 
 ## Integration test strategy
 It's convenient to use the Apollo Integration test server during development, particularly with Wallaby, as it serves the GraphQL server without booting a HTTP server. The same tests are run on the CI server to provide end-to-end assurance, using an instance of ApolloClient and the API running in a [Docker container](../../test/docker-compose.yml).
-

docs/developer/configuration.md

@@ -0,0 +1,14 @@
+# Configuration
+## ENVs
+### `API_PORT`: Number
+Default: `3100`
+
+### `HASURA_URI`: String
+Hasura GraphQL server endpoint eg `http://localhost:8090/v1/graphql`
+
+## `QUERY_DEPTH_LIMIT`: Number 
+Default `10`
+Used to set [depthLimit](https://github.com/stems/graphql-depth-limit)
+
+## `TRACING`: Boolean
+Passed as an option to [ApolloServer](https://www.apollographql.com/docs/apollo-server/api/apollo-server/)

docs/maintainer/README.md

@@ -0,0 +1,5 @@
+# Maintainer
+
+- [Database Snapshot](./db-snapshot.md)
+- [Hasura](./hasura.md)
+- [Releasing New Versions](./releasing_new_versions.md)

docs/refresh_db/README.md → docs/maintainer/db-snapshot.md

@@ -1,4 +1,6 @@
-# Refresh Test DB Dump
+# DB Snapshot
+
+The project uses a small snapshot from the mainnet as the development and test dataset, as this allows concrete assertions to remain mostly static, and removes the need to stand up a Cardano network.  
 
 1. clone `cardano-docker-stack` from GH
 2. From cardano-docker-stack, run `./scripts/start_mainnet.sh`

docs/maintainer/releasing_new_versions.md

@@ -0,0 +1,7 @@
+# Releasing New Versions
+1. Branch from `master`
+2. Update the changelog with meaningful descriptions, and links to PRs where appropriate
+3. Use [npm version](https://docs.npmjs.com/cli/version) specifying `-no-git-tag-version` and `--sign-git-tag` using the appropriate [SemVer](https://semver.org/) compliant type.
+4. Push the branch and merge into `master` via a PR
+5. Use the GitHub GUI to create a release and tag from `master` with the prefix `v`, matching the version in [package.json](../../package.json)
+6. The [CD pipeline](../../Jenkinsfile) will build a Docker image for the version and deploy it to dockerhub.

docs/qa/README.md

@@ -0,0 +1,21 @@
+# QA
+
+## System Requirements
+- Docker v19+
+- docker-compose 1.24+
+
+## Launch the _mainnet_ snapshot test stack
+### Start
+```
+docker-compose -f test/docker-compose.yml up
+```
+Finding the GraphQL Playground at http://localhost:3100 verifies the env is ready
+
+### Test
+At this point the [API can be interacted with](../api_consumer/interacting_with_the_api.md), or testing tools aimed at the GraphQL server running at http://localhost:3100/graphql. This codebase implements a CI with end-to-end test and CD into a staging environment for both the mainnet and testnet. The [test suites](../../src/__test__/tests) are scoped to the GraphQL queries, as defined in the [schema](../../src/schema.graphql), and are required to be passing before new code is merged. 
+
+### Stop and cleanup
+`docker-compose -f test/docker-compose.yml down -v`
+
+### Troubleshooting
+If you have a port clash on the host, change the mapping in the [docker-compose](../../test/docker-compose.yml)