Development Environment

We're really excited that you are interested in contributing to Kloud Workspace. Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

• Code of Conduct →
• Contribution Workflow (Optional) →

Prerequisites

Before you begin, check your prerequisites meet the minimum requirements versions:

• Python (optional): >=3.8
• NodeJS (docs): >=18
• Golang (cli): >=1.21

Python

$ python --version
Python 3.11.2

NodeJS

$ node --version
v22.11.0

Golang

$ go version
go version go1.24.0 linux/amd64

Setup

You can clone the repository and run it locally:

1. Clone the repository

Workspace

git clone https://github.com/kloudkit/workspace

Documentation

git clone https://github.com/kloudkit/ws-docs

CLI

git clone https://github.com/kloudkit/ws-cli

2. Install dependencies

Linting (optional)

pip install pre-commit

Documentation

yarn install

CLI

go install

3. Linting (Optional)

pre-commit run --all-files
pre-commit install

💡 TIP

This step is automatically run on all pull requests and commits. If you choose to skip this step, that's OK, we will run it for you during CI.

4. Run a local development (docs) server

yarn run docs:dev

Testing

Ensure your local environment meets the minimum requirements before running tests:

• Python: >=3.11
• Docker: >=25

1. Install Test Dependencies

Install the required Python packages for testing:

pip install -r tests/requirements.txt

2. Run Tests

When executing tests for the first time, the test suite will build a Docker testing image (ghcr.io/kloudkit/workspace:tests) automatically.

pytest

⚠️ WARNING

If you've updated the implementation code but haven't rebuilt the test image, the tests may run against an outdated image.

Make sure to rebuild the image before running tests.

3. Optional Execution Flags

• Custom Docker Tag: Use the --shed-tag flag to specify a custom Docker image tag.

  pytest --shed-tag=my-custom-tag

• Force Image Rebuild: Add the --shed-rebuild flag to rebuild the Docker image.

  pytest --shed-rebuild

• Require Image: Add the --shed-require-image flag to require an existing pre-built Docker image.

  pytest --shed-rebuild