Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
246 lines (162 loc) · 10.2 KB

CONTRIBUTING.md

File metadata and controls

246 lines (162 loc) · 10.2 KB

Contributing to the WunderGraph Cosmo Repository

Before contributing to the WunderGraph Cosmo repository, please open an issue to discuss the changes you would like to make. Alternatively, you can also open a discussion in the WunderGraph Discussions. We are open to all kinds of contributions, including bug fixes, new features, and documentation improvements.

The following sections provide a guide on how to contribute to the WunderGraph Cosmo repository.

Prerequisites

This guide assumes you have already installed the following software:

Other Dependencies

These are not core requirements, but they are needed for certain parts of the development workflow:

  • bun: Used for building and testing TypeScript-based router plugins. Some integration tests compile Bun binaries as part of the testing process, so having Bun installed is required when working with those components.

Monorepo

NPM packages are managed as a pnpm workspace. This means during development all dependencies are linked. The root package.json provides all scripts you need to orchestrate the development workflow.

Bootstrap the development environment

Most of the project have a .env.example file. Replace .env.example with .env and fill in the required values.

Bootstrap the repository

You can bootstrap the repository with the following command:

make

Ready! You can now start contributing to the WunderGraph Cosmo repository. Feel free to open an issue or pull request to add a new feature or fix a bug.

Go workspace

According to best practices, we don't commit the go.work or go.work.sum files. Those files are personal to each developer. As a result, we use the go.mod file to manage the dependencies and overwrites. You can still create go.work file in the root of the repository if you are feeling more comfortable with it or to improve tooling support.

Example

go 1.25

use (
	./demo
	./router
	./router-tests
)

// Here you can add custom replacements

Conventional Commit Standard

We use conventionalcommits for changelog generation and more structured commit messages.

If you want to enforce this standard, you can set up a pre-commit hook. This functionality is provided by husky. Run pnpm husky to install pre-commit hooks which format code and check commit message format. In some setup, you have to tell husky where to find your package manager or binaries. Here is the file husky.sh which you should put in your home's configuration directory (~/.config/husky/husky.sh).

export NVM_DIR=/home/starptech/.nvm
[ -s /home/starptech/.nvm/nvm.sh ] && \. /home/starptech/.nvm/nvm.sh  # This loads nvm

# golang
export PATH=$PATH:/usr/local/go/bin
export PATH="$PATH:$(go env GOPATH)/bin"

For JetBrains users

This plugins simplifies the commit message creation process.

Pull Requests Conventions

We merge all pull requests in squash merge mode. You're not enforced to use conventional commit standard across all your commits, but it's a good practice and increase transparency. At the end it's important that the squashed commit message follow the standard.

Local Development

Prerequisites

All services work with environment variables. You can find the default values in the .env.example file. Please copy the variables to .env (the same for studio but with .env.local) and adjust the values to your needs.

# In the root directory (cosmo/)
# Copy controlplane environment file
cp controlplane/.env.example controlplane/.env

# Copy studio environment file
cp studio/.env.local.example studio/.env.local

# Copy cli environment file
cp cli/.env.example cli/.env

# Copy router environment file
cp router/.env.example router/.env

Bootstrapping Cosmo for local development is easy. Just run the following commands in order:

# In the root directory (cosmo/)
# 1️⃣ Setup the repository, build libraries and start all services (Wait a few seconds until Keycloak is ready)
# You can check whether Keycloak is running by going to localhost:8080. It should show sign-in page
make

# 2️⃣ Run migrations and seed the database
make migrate && make seed

# 3️⃣ Start the control plane
make start-cp

# 4️⃣ Create the demo and copy the JWT printed at the bottom
make create-demo

# 5️⃣ Start the subgraphs
OTEL_AUTH_TOKEN=<jwt-token> make dc-subgraphs-demo

# 6️⃣ Put the JWT from the previous step into the router/.env as GRAPH_API_TOKEN and start the router
make start-router

# ✨ Finally, Start the studio (http://localhost:3000) and explore the Cosmo platform
make start-studio

Navigate to http://localhost:3000/ and login with the default credentials:

Username: foo@wundergraph.com
Password: wunder@123

Navigate to the cli directory and replace .env.example with .env. After that you can run commands against your local Cosmo instance.

cd cli && pnpm wgc -h

Clean up all containers and volumes by running make infra-down-v. You can repeat the steps above to bootstrap the platform again.

Docker Compose

We manage multiple compose files:

  • docker-compose.yml: The default compose file. It contains all services that are required to run the platform for development.
  • docker-compose.full.yml: This compose file contains the full Cosmo platform. It is used for demo and testing.
  • docker-compose.cosmo.yml: This compose file allows to build all Cosmo components and manage them in a single compose file. It is used for testing and releasing.

Code Coverage

We use Codecov for code coverage. Code coverage is used for both PRs and also our default branch main.

Workaround for uploading to main

Codecov relies on commit hashes to map code to Codecov reports, however unfortunately we use "Squash Merge", which means that the HEAD of any merged PR is never present on main post-merge, leading to no code coverage uploaded for main (which is used as a base for comparisons).

In order to circumvent this we do the following steps:

  • Upload Codecov reports from PR runs to GitHub as artifacts for the PR's HEAD commit
  • Upon merge we find the PR and it's HEAD commit using the GitHub rest API
  • We find the github artifact from this commit hash
  • We then upload it again, but this time it acts as if it was uploaded from main

Adding new projects

When you add a new project (i.e. a subfolder in the cosmo repository root), if you wish to add code coverage for it you can follow these steps:

  • Add a flag in the codecov.yaml for your project with the folder name, this is important so coverage does not get overwritten (for example if a router pr gets merged, cli coverage won't be set to empty for that commit)
flags:
  router:
    paths:
      - router
    carryforward: true
  • You should be running tests in ci for your project via a GH Workflow, You need to add the GH Workflow name to codecov-post-merge.yaml, the line you are looking for will look something like this
workflow-paths: .github/workflows/cli-ci.yaml,.github/workflows/router-ci.yaml,

Ensure you add the full relative path from the cosmo repository root and it is comma-separated, e.g.: for graphqlmetrics ,.github/workflows/graphqlmetrics-ci.yaml

Clean up a compose stack before starting another one!

Compose Profiles Overview

dev Profile

The dev profile is the primary profile used to set up the required infrastructure containers for the local demo environment. The setup and teardown processes are managed through the following Make targets:

  • infra-up: Starts the infrastructure containers.
  • infra-down: Stops and removes the infrastructure containers.
  • infra-down-v: Stops and removes the infrastructure containers and volumes.

debug Profile

The debug profile provides additional containers to facilitate local debugging, particularly when working with the Cosmo Router. These containers include tools such as:

  • Prometheus
  • Jaeger
  • Grafana

The setup and teardown of the debug-specific services are handled through the following Make targets:

  • infra-debug-up: Starts the debugging containers.
  • infra-debug-down: Stops and removes the debugging containers.
  • infra-debug-down-v: Stops and removes the debugging containers and volumes.

Usage

  1. Use the dev profile to set up the core infrastructure required for the local demo.
  2. Optionally, use the debug profile to enable additional debugging tools.

These profiles can be managed independently or in conjunction, depending on your local development and debugging requirements. NOTE: The debug profile is not required for the core functionality of the Cosmo platform, but you need to have the infrastructure containers running to use the debugging tools.

Grafana

Grafana is available at http://localhost:9300 with the default credentials:

Username: admin
Password: admin