Skip to content

Latest commit

 

History

History
145 lines (93 loc) · 7.43 KB

CONTRIBUTING.md

File metadata and controls

145 lines (93 loc) · 7.43 KB
Raw

How to Contribute

Thank you for looking at this. We, at Tracetest, are really excited to have you contribute on the project with us.

The main lines of communication with our team are through Github issues or Slack. Feel free to ask any questions!

Developing

Development can be conducted using any GoLang and Typescript compatible IDE/editor (e.g., Jetbrains GoLand, VSCode).

There are four places where you develop new things on Tracetest: on the CLI, on the API Server, on the Web UI and on the Documentation website.

CLI

Written in Golang, the CLI code is stored in the folder ./cli. You can see what options you have to test and build the application by typing make help inside the folder.

To test its integration with our API, you can run a local API server on your machine by running one of our examples with docker compose. For instance:

cd ./examples/tracetest-jaeger
docker compose up -d

Remember that you need a file pointing to that server by configuring the CLI using the tracetest configure command or using the flag -c with a valid config file location, like config.yaml with the following content:

scheme: http
endpoint: localhost:11633
analyticsEnabled: false

API Server

Written in Golang, the API Server code is stored in ./server. You can see what options you have to test and build the application by typing make help inside the folder.

To run the server along the database and the Open Telemetry collector, you can run docker compose at the root folder of Tracetest, by executing:

docker compose up postgres otel-collector

Web UI

Written in Typescript and using Node.js tools, the Web UI code is stored in the folder ./web. You can see what options you have to test and build the application by seeing the package.json scripts here.

Like the CLI, to connect to the API, you can run a local API server on your machine by running one of our examples with docker compose. For instance:

cd ./examples/tracetest-jaeger
docker compose up -d

Documentation Website

Our docs are written in Markdown and the website is generated by docusaurus, the documentation is stored in the folder ./docs. You can see what options you have to test and build the application by seeing the package.json scripts here.

Testing

We strive to have tests verify every important corner of our code-base. It will be greatly appreciated if your PR's include tests for the changes you propose.

Submitting Changes

Please create a Github Pull-Request with a clear list of what you've done (read more about pull requests). When you send a pull request, we would appreciate included use-case examples. Please follow our coding conventions (below) and make sure all of your commits are atomic (one feature per commit).

Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:

$ git commit -m "A brief summary of the commit
> 
> A paragraph describing what changed and its impact."

Coding Conventions

Start reading our code and you'll get the hang of it. We use code formatting tools like eslint and go vet to help maintain peace in the galaxy.

If you have any doubts about coding standards you can follow Effective Go or Go styleguide for Golang and Typescript styleguide for Typescript.

Many thanks, Kubeshop

Building, running, and e2e testing

As described, the project consists of 3 main components: CLI, server, and web. Each components' directory provides a standard language way to build and test:

  • Web: uses npm. Commands such as npm start build, npn ci, etc are available.
  • CLI: it is a go module. It can be built with go build ., tests are run with go test ./... etc
  • Server: it is a go module. It can be built with go build ., tests are run with go test ./... etc

CLI and Server are mainly built from the project root using GoReleaser to simplify packaging and distribution.

The server is responsible for serving both the API and the web UI. The easiest way to mix those 2 things for distribution is with docker. We rely on GoReleaser again for packaging all those things together.

We also use a few environment variables to configure the build.

It becomes evident that it's not very practical during development to keep all this things in mind. We provide 2 main ways to build, run and test Tracetest:

Makefile

We provide a Makefile with a few targets that helps build all the parts in a development configuration without a lot of intervention. The more common used targets are:

  1. make help: shows a list of commands with a description.
  2. make build-docker: builds the current code (web, cli, server) and packages it all in a tagged docker image. The default image will be "kubeshop/tracetest:ev"
  3. make build-go: build the cli and server only
  4. make build-web: build the web UI only
  5. make run: depends on the build-docker target. It build the image and starts a docker compose stack. The web UI will be available at http://localhost:111633
  6. make clean: removes all built artifacts

A note on go builds: When running make build-docker, the go binaries are built to be run inside a docker container. Docker containers are always Linux, regardless of the host OS. This means that if you run make build-docker on a mac, the targets dist/tracetest and dist/tracetest-server won't run on the mac host. You need to rebuild the go binaries (using make build-go)after building the docker image if you want to run them directly on the host MacOS.

run.sh script

For unit tests, we rely on each languages main unit test approach (cracto test for web, go test for go). For more complex end-to-end test, it's not that simple. You need to have a more or less complete deployment available, with a known initial state. This can be cumbersome to setup manually, so we have the run.sh script.

This script provides a few commands to help manage this test target deployment. It relies on the Makefile and on docker-compose.yaml to build and create it.

Exmaple usage:

Build everything, and start clean

./run.sh down build up tracetest-logs

This command firt resets the environment (down == docker compose down), build the docker image (build == make docker-build), starts the environment (up == docker compose up -d) and finally starts following the tracetest logs (tracetest-logs == docker compose -f tracetest)

Run the server e2e trace based tests

./run.sh tracetests

THis will run the server e2e trace based testing suite, also known as dogfooding. This assumes the test environment is already started.

Clean, start, run tests, and reset

./run.sh down build up tracetests down

This resets the state, build, starts the test environment, runs the trace based test suit, and resets everything agian.

Run the web UI e2e trace based tests

./run.sh down build up cypress down