Project: Tracetest (Observability and Analysis / Observability)
File: CONTRIBUTING.md

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 or . Feel free to ask any questions! 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. 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 with `docker compose`. For instance: ```sh 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: ```yaml scheme: http endpoint: localhost:11633 analyticsEnabled: false ``` 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: ```sh docker compose up postgres otel-collector ``` 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 . Like the CLI, to connect to the API, you can run a local API server on your machine by running one of our with `docker compose`. For instance: ```sh cd ./examples/tracetest-jaeger docker compose up -d ``` 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 . 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. Please create a Github Pull-Request with a clear list of what you've done (read more about ). 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." Start reading our code and you'll get the hang of it. We use code formatting tools like and to help maintain peace in the galaxy. If you have any doubts about coding standards you can follow or for Golang and for Typescript. Many thanks, Kubeshop As described, the project consists of 3 main components: CLI, server, and

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 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: We provide a 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: make help: shows a list of commands with a description. 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" make build-go: build the cli and server only make build-web: build the web UI only make run: depends on the build-docker target. It build the image and starts a . The web UI will be available at `http://localhost:111633` 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. 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 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. Build everything, and start clean ```sh ./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 ```sh ./run.sh tracetests ``` THis will run the server e2e trace based testing suite, also known as . This assumes the test environment is already started. Clean, start, run tests, and reset ```sh ./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 ```sh ./run.sh down build up cypress down ```