From 6219a1963059ee214c104c6b193f4e26d96a54db Mon Sep 17 00:00:00 2001 From: Rhys Bartels-Waller Date: Fri, 24 Jan 2020 19:45:08 +1100 Subject: [PATCH] Reorganisation of docs, addition of maintainer and QA docs, invalid default config, and specify new branching strategy --- README.md | 14 ++++++++----- docs/README.md | 21 ++----------------- docs/api_consumer/interacting_with_the_api.md | 7 +++++-- docs/developer/README.md | 7 +++---- docs/developer/configuration.md | 14 +++++++++++++ docs/maintainer/README.md | 5 +++++ .../README.md => maintainer/db-snapshot.md} | 4 +++- .../README.md => maintainer/hasura.md} | 0 docs/maintainer/releasing_new_versions.md | 7 +++++++ docs/qa/README.md | 21 +++++++++++++++++++ 10 files changed, 69 insertions(+), 31 deletions(-) create mode 100644 docs/developer/configuration.md create mode 100644 docs/maintainer/README.md rename docs/{refresh_db/README.md => maintainer/db-snapshot.md} (72%) rename docs/{hasura/README.md => maintainer/hasura.md} (100%) create mode 100644 docs/maintainer/releasing_new_versions.md create mode 100644 docs/qa/README.md diff --git a/README.md b/README.md index 62ddfdb0..e02c7ba5 100644 --- a/README.md +++ b/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) diff --git a/docs/README.md b/docs/README.md index 2268d29c..e9bd785d 100644 --- a/docs/README.md +++ b/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/) \ No newline at end of file + - [Maintainer](./maintainer) + - [QA](./qa) diff --git a/docs/api_consumer/interacting_with_the_api.md b/docs/api_consumer/interacting_with_the_api.md index 9a3f059a..1ce477ed 100644 --- a/docs/api_consumer/interacting_with_the_api.md +++ b/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 diff --git a/docs/developer/README.md b/docs/developer/README.md index 030cd48e..426b8038 100644 --- a/docs/developer/README.md +++ b/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). - diff --git a/docs/developer/configuration.md b/docs/developer/configuration.md new file mode 100644 index 00000000..d20fa2c0 --- /dev/null +++ b/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/) \ No newline at end of file diff --git a/docs/maintainer/README.md b/docs/maintainer/README.md new file mode 100644 index 00000000..3e542958 --- /dev/null +++ b/docs/maintainer/README.md @@ -0,0 +1,5 @@ +# Maintainer + +- [Database Snapshot](./db-snapshot.md) +- [Hasura](./hasura.md) +- [Releasing New Versions](./releasing_new_versions.md) \ No newline at end of file diff --git a/docs/refresh_db/README.md b/docs/maintainer/db-snapshot.md similarity index 72% rename from docs/refresh_db/README.md rename to docs/maintainer/db-snapshot.md index 428ce96c..fe0b51af 100644 --- a/docs/refresh_db/README.md +++ b/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` diff --git a/docs/hasura/README.md b/docs/maintainer/hasura.md similarity index 100% rename from docs/hasura/README.md rename to docs/maintainer/hasura.md diff --git a/docs/maintainer/releasing_new_versions.md b/docs/maintainer/releasing_new_versions.md new file mode 100644 index 00000000..992dcc60 --- /dev/null +++ b/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. diff --git a/docs/qa/README.md b/docs/qa/README.md new file mode 100644 index 00000000..9a26d286 --- /dev/null +++ b/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) \ No newline at end of file