From c7919fa2a0c72cca8fd8df40ea996a27f427ce43 Mon Sep 17 00:00:00 2001 From: Rukmal Weerawarana Date: Wed, 28 Sep 2022 12:52:23 +0530 Subject: [PATCH] Update documentation Closes #5 --- .github/workflows/pages.yml | 1 + .github/workflows/release.yml | 4 + Makefile | 10 +-- README.md | 141 +++++++++++++++++++++++++++++++++- client/Module.md | 5 ++ client/Package.md | 2 + 6 files changed, 155 insertions(+), 8 deletions(-) create mode 100644 client/Module.md diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 2efd35b..c81b8aa 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -5,6 +5,7 @@ on: # Runs on pushes targeting the default branch push: branches: ["main"] + workflow_call: # Allow one concurrent deployment concurrency: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b5016cf..7e37ef2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -85,3 +85,7 @@ jobs: env: WORKING_DIR: client BALLERINA_CENTRAL_ACCESS_TOKEN: ${{ secrets.BALLERINA_CENTRAL_ACCESS_TOKEN }} + update-documentation: + name: Update documentation + needs: push-api-client + uses: avinya-foundation/global-data/.github/workflows/pages.yml@main diff --git a/Makefile b/Makefile index 486490f..69dd96a 100644 --- a/Makefile +++ b/Makefile @@ -3,19 +3,19 @@ # Run GitHub Workflows with Act ############################### -.PHONY: run -run: ## Run GitHub workflows with act - act -v +.PHONY: push +run: ## Run push GitHub workflows with act + act -v push .PHONY: clean clean: ## Clean docker containers and volumes (causes act to break sometimes) docker rm -f $(shell docker ps -a -q) docker volume rm $(shell docker volume ls -q) -.PHONY: all +.PHONY: app all: ## Cleans up docker containers, and runs GitHub workflows with act $(MAKE) clean - $(MAKE) run + $(MAKE) push # Util ####### diff --git a/README.md b/README.md index 34b524e..2c5e432 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,146 @@ -## Avinya Foundation Global Data Service +# Avinya Foundation Global Data Service The Avinya Foundation's Global Data Service underlies the Avinya Foundation technology stack, and provides a universal interface to foundation data to all applications in the organization. +## Features + +The global data service provides a generalized interface to foundation data for all internal clients at the Avinya Foundation. This includes applications across many domains; human resource management, student admissions, enterprise resource planning, and class management. + +The main features are: + +- Ballerina GraphQL API that exposes a semantically enriched global database; +- Generated Ballerina GraphQL client to query the API; +- Automated deployment and management of the GraphQL API on [Choreo](https://wso2.com/choreo/); +- Generalized data model to ensure interoperability and persistence across application domains in the organization; +- Robust test infrastructure, locally, and in the cloud. + ## Component Documentation -- [GraphQL API Documentation](https://avinya-foundation.github.io/global-data/api_doc/) +- [GraphQL API Ballerina Documentation](https://avinya-foundation.github.io/global-data/api_doc/) +- [GraphQL Client Ballerina Documentation (on Central)](https://lib.ballerina.io/avinyafoundation/global_data_client/latest) + +## Project Status + +### Build and Test | ![Build and test pipeline](https://github.com/Avinya-Foundation/global-data/actions/workflows/push.yml/badge.svg) + +*Build project and run tests* + +Builds database container, and pushes to `ghcr.io`. Builds the `api/` ballerina project, and runs tests. Generates GraphQL client from the schema in `api/schema`. + +### Generate Project Documentation | ![GitHub Pages pipeline](https://github.com/Avinya-Foundation/global-data/actions/workflows/pages.yml/badge.svg) + +*Generate project documentation* + +Use `bal doc` to build ballerina API documentation for the `api`. Adds these artifacts to the `gh-pages` branch, and sets up a Jekyll site with the [Cayman](https://github.com/pages-themes/cayman) theme. + +### Release Pipeline | ![Release pipeline](https://github.com/Avinya-Foundation/global-data/actions/workflows/release.yml/badge.svg) + +*Main `global-data` release workflow* + +Bumps the project version numbers in `Ballerina.toml` files based on the release tag. Updates Microsoft Azure database schemas. Pushes GraphQL API client to Ballerina Central. + +## Development + +> Note: GitHub Pages does not yet support mermaid. To see rendered diagrams, look at the [project `README` on GitHub](https://github.com/Avinya-Foundation/global-data#readme). + +### CI/CD + +Global Data Service uses [GitHub Actions](https://github.com/features/actions) for managing CI/CD. Local pipeline execution is enabled with [act](https://github.com/nektos/act). + +The logical setup of the GitHub Actions workflows is illustrated below. The actions are divided into 3 functionally separate workflows; `push`, `pages`, and `release`. + +> Note: In all workflows, all paths must evaluate to the `Success State`, or the workflow fails. + +These actions run at different points in the development lifecycle. The relationship between the 3 workflows, and detail for each of the workflows are illustrated below: + +- Meta workflow + +```mermaid +stateDiagram-v2 + push: push workflow + pages: pages workflow + release: release workflow + [*] --> push: commit/PR created + push --> pages: merged to main + pages --> release: new release cut +``` + +- [`push`](.github/workflows/push.yml) workflow + +```mermaid +stateDiagram-v2 + db_setup: Database Setup + ghcr_registry: GitHub Container Registry + idempotence_test: Database Idempotence Test + graphql_test: GraphQL API Test + graphql_client_generate: Generate GraphQL Client + success: Success State + failed: Failed State + repo: Caller Branch + [*] --> db_setup: commit/PR created + db_setup --> ghcr_registry: successful db build + db_setup --> failed: db build failed + ghcr_registry --> idempotence_test: pull db image + idempotence_test --> success: test passed + idempotence_test --> failed: test failed + ghcr_registry --> graphql_test: pull db image + graphql_test --> failed: test failed + graphql_test --> graphql_client_generate: tests passed + graphql_client_generate --> failed: generation failed + graphql_client_generate --> repo: commit client + repo --> success + success --> [*] + failed --> [*] +``` + +- [`pages`](.github/workflows/pages.yml) workflow + +```mermaid +stateDiagram-v2 + main: main Branch + gh_pages: gh-pages Branch + build_api_doc: Build Ballerina API Documentation + api_doc: API Documentation + success: Success State + failed: Failed State + [*] --> main: checkout + main --> build_api_doc + build_api_doc --> failed: bal doc failed + build_api_doc --> api_doc: bal doc succeeded + api_doc --> gh_pages: commit + gh_pages --> success + success --> [*] + failed --> [*] +``` + +- [`release`](.github/workflows/release.yml) workflow + +```mermaid +stateDiagram-v2 + main: main Branch + version_number: Update Package Version Number + push_schema: Update Database Schema + azure_db: Azure Database + bal_central: Ballerina Central + success: Success State + failed: Failed State + [*] --> main: create release + main --> version_number: extract version number + version_number --> failed: update failed + version_number --> push_schema: update successful + push_schema --> azure_db: authenticate and push + azure_db --> failed: schema update failed + azure_db --> bal_central: push API client + bal_central --> failed: push failed + bal_central --> success: push succeeded + failed --> [*] + success --> [*] +``` + +### Local Workflow Execution Notes -### Notes for Running Tests +> Note: "Local" means running the tests on the developer's machine with [`act`](https://github.com/nektos/act). - Need to change `HOST` to `localhost` in `tests/Config.toml` for local tests to run correctly. +- The [`Makefile`](Makefile) contains recipes for running the push pipeline with `act`. +- Some tests are duplicated with local-only logic. Specifically, all tests that require the database container have duplicate logic for local execution due to a limitation with `act` and [GitHub service containers](https://docs.github.com/en/actions/using-containerized-services/about-service-containers). For more information, see https://github.com/nektos/act/issues/173. diff --git a/client/Module.md b/client/Module.md new file mode 100644 index 0000000..507fd5a --- /dev/null +++ b/client/Module.md @@ -0,0 +1,5 @@ +# Avinya Foundation Global Data Service GraphQL Client + +Ballerina Documentation for the Avinya Foundation's Global Data Service client. + +To return to the main documentation page, [click here](https://avinya-foundation.github.io/global-data/). diff --git a/client/Package.md b/client/Package.md index 5d3398d..72d8619 100644 --- a/client/Package.md +++ b/client/Package.md @@ -1 +1,3 @@ # Avinya Foundation Global Data Service + +For more information, see: https://avinya-foundation.github.io/global-data.