Contributing

We love every form of contribution. By participating in this project, you agree to abide to the TypeStream code of conduct.

Prerequisites

• Gradle
• Docker and Docker Compose
• Minikube
• Go
• Protobuf
• Make
• Redpanda (you need rpk locally. Min version: v24.1.2)

Set up your machine

TypeStream is a Kotlin gRPC application. We use Gradle as our build tool. You can find the instructions to install it here.

While it's not required, we recommend IntelliJ IDEA to work with our Kotlin codebase.

We also provide an official CLI application called typestream, available at /cli. The CLI is written in Go.

Clone TypeStream from source:

$ git clone https://github.com/typestreamio/typestream.git
# Cloning into 'typestream'...
# etc..
$ cd typestream

A good way of making sure everything is all right is running the test suite:

./gradlew check

For the CLI, you can run:

cd cli
make

Open an issue if you run into any problem.

Building and running TypeStream

You can build the TypeStream by running:

./gradlew build

If you use IntelliJ IDEA, we provide a run configuration that you can use to run the server. It uses the script scripts/dev/kafkastart.sh to start a local Redpanda cluster.

Otherwise, you can run the server with:

./scripts/dev/server.sh

and then, from another window terminal, the CLI with:

./scripts/dev/shell.sh

K8s mode

While this is sufficient to run the server and play around with the CLI features, it doesn't allow you to work with TypeStream "cloud native" features (such as the long running jobs scheduler).

To do so, you need to run TypeStream in "k8s mode". The first thing to do is to push the beta images to a local docker registry. In one terminal, run:

docker run --rm -it --network=host alpine ash -c "apk add socat && socat TCP-LISTEN:5001,reuseaddr,fork TCP:$(minikube -p typestream ip):5001"

so that the docker registry is available at localhost:5001. Then, in another terminal, run:

docker run -d -p 5001:5000 --restart=always --name registry registry:2

to push the beta images to the local registry. Finally, run:

cd cli
make
./typestream k8s create # add --redpanda to also start a Redpanda cluster inside k8s

to create a local k8s cluster with Minikube using the beta images.

Once you have an healthy minikube cluster, you can connect to the TypeStream server with the CLI as long as you're running this command in the background:

kubectl port-forward -n typestream svc/server 4242:4242

Local mode

To help people getting started, we provide a few local commands. If you're to test TypeStream in this context, you need a local docker registry:

docker run -d -p 5001:5000 --restart=always --name registry registry:2

and then you can run:

./scripts/dev/push-images.sh

You're now ready to run the server in local mode:

cd cli
make
./typestream local start
./typestream local seed

Testing

We try to cover as much as we can with testing. The goal is having each single feature covered by one or more tests. Adding more tests is a great way of contributing to the project!

Running the tests

Once you are set up, you can run the test suite with one command:

./gradlew test

Test your change

You can create a branch for your changes and try to build from the source as you go:

./gradlew check

Submit a pull request

Push your branch to your TypeStream fork and open a pull request against the main branch. We use conventional commits for our commit messages so follow the convention in the title of your PR (otherwise, the build will fail).