Release Policy

This document describes how releases are managed in the thyris-sz monorepo, and which artifacts are considered official for each product.

The repository contains three main products:

thyris-sz – the main Go service / gateway
tszclient-go – Go SDK (Go client library)
tszclient-py – Python SDK (Python client library)

Releases are driven by a single source repository Actions workflow and a set of product-specific shell scripts under ci/.

1. Versioning & Tagging

1.1. Products and tags

Each product has its own version stream and tag prefix:

thyris-sz (service)
- Tag format: thyris-sz-vMAJOR.MINOR.PATCH
- Example: thyris-sz-v1.3.0
tszclient-go (Go SDK)
- Tag format: tszclient-go-vMAJOR.MINOR.PATCH
- Example: tszclient-go-v0.1.0
tszclient-py (Python SDK)
- Tag format: tszclient-py-vMAJOR.MINOR.PATCH
- Example: tszclient-py-v0.1.5

Tags are product-specific; bumping a version for one product does not imply a change in the others.

1.2. Bump types

The workflow exposes the classic semantic versioning bump types:

patch – bug fixes, no API / contract changes
minor – backward-compatible new features
major – breaking changes

These are passed into the product-specific release scripts and used to calculate the next semantic version for that product.

2. Official Artifacts per Product

2.1. thyris-sz (service)

Official artifact(s) (current stage):
- Git tag: thyris-sz-vX.Y.Z
- source repository Release (optional, if created manually later) + auto-generated source archives
- Built binary: thyris-sz (produced by the release script)

Note: There is currently no Docker image build/publish wired into the release workflow. This can be added later (e.g., pushing to GHCR, ECR, or another registry).

2.2. tszclient-go (Go SDK)

Module path:

module source.example/thyris/safe-zone/pkg/tszclient-go

Usage from external Go projects:

import tszclient "source.example/thyris/safe-zone/pkg/tszclient-go"

Official artifacts:
1. Go module at source.example/thyris/safe-zone/pkg/tszclient-go:
  - Resolved by go get using tags tszclient-go-vX.Y.Z.
2. source repository Release asset (SDK-only zip):
  - File name: tszclient-go-X.Y.Z.zip
  - Contents:
    - pkg/tszclient-go/**
    - examples/go-sdk-demo/**
    - Excludes:
      - **/__pycache__/*
      - *.pyc
      - *.pyo
  - This is the recommended "single archive" for consumers who want just the Go SDK + example code.
3. Source code archives (auto-generated by source repository):
  - Source code (zip) / Source code (tar.gz) - full monorepo snapshot at the tagged commit.
  - These are not SDK-only; they contain the entire repository.

2.3. tszclient-py (Python SDK)

PyPI package name: tszclient-py
Project definition: pyproject.toml under repository root.
Official artifacts:
1. PyPI package:
  - Wheel and sdist built from pyproject.toml
  - Version: [project].version (e.g., 0.1.5)
  - Published to PyPI via twine.
2. source repository Release asset (SDK-only zip):
  - File name: tszclient-py-X.Y.Z.zip
  - Contents:
    - pkg/tszclient_py/**
    - examples/python-sdk-demo/**
    - Excludes:
      - **/__pycache__/*
      - *.pyc
      - *.pyo
3. Source code archives (auto-generated by source repository):
  - Source code (zip) / Source code (tar.gz) - full monorepo snapshot at the tagged commit.

3. Release Workflow (source repository Actions)

The main release workflow is defined in:

.source repository/workflows/release.yml

It is manually triggered via workflow_dispatch.

3.1. How to run a release

Push your changes to the desired branch (e.g., main or a release branch).
In source repository:
- Go to the repository -> Actions tab.
- Select the Product Release workflow.
- Click “Run workflow”.
In the dialog:
- Select the branch to release from.
- Choose the product:
  - thyris-sz
  - tszclient-go
  - tszclient-py
- Choose the bump type:
  - patch / minor / major.
Click “Run workflow”.

The workflow will:

Checkout the repository with full history (fetch-depth: 0).
Set up Go and/or Python depending on the product.
Run the corresponding scripts/release/release_<product>.sh script.
For SDKs, package SDK-only zip archives and attach them to a source repository Release.

3.2. Product-specific behaviors

thyris-sz

Release script: scripts/release/release_thyris-sz.sh

Steps:

Determine the last thyris-sz-v* tag (if any).
Check if there are changes outside client directories since the last tag:
- Includes: everything except pkg/tszclient-go, pkg/tszclient_py.
If no changes -> skip release.
Otherwise:
- Compute new version according to bump.
- Run tests:
```
go clean -testcache
go test -tags test ./tests/...
```
- Build the binary:
```
go build -o thyris-sz .
```
- Create and push tag: thyris-sz-vX.Y.Z.

Official artifact is currently the tag + source; binary can be attached manually if needed.

tszclient-go (Go SDK)

Release script: scripts/release/release_tszclient-go.sh

Steps:

Determine the last tszclient-go-v* tag.
Check if there are changes since the last tag in:
- pkg/tszclient-go/**
- tests/unit/tszclient_go_chat_test.go
If no changes -> skip release.
Otherwise:
- Compute new version according to bump.
- Run tests (shared test tree, with test build tag):
```
go clean -testcache
go test -tags test ./tests/...
```
- Create and push tag: tszclient-go-vX.Y.Z.

Then the workflow:

Packages Go SDK + Go example into a zip:

zip -r "tszclient-go-${VERSION}.zip" \
  pkg/tszclient-go \
  examples/go-sdk-demo \
  -x '**/__pycache__/*' '*.pyc' '*.pyo'

Creates/updates a source repository Release for that tag and attaches the zip.

tszclient-py (Python SDK)

Release script: scripts/release/release_tszclient-py.sh

Steps:

Determine the last tszclient-py-v* tag.
Check if there are changes since the last tag in:
- pkg/tszclient_py/**
- pyproject.toml
If no changes -> skip release.
Otherwise:
- Read current [project].version from pyproject.toml.
- Compute new version according to bump and update pyproject.toml.
- (Optional) run tests (hook is present; add pytest here if needed).
- Build distributions:
```
python -m build
```
- Publish to PyPI:
```
python -m twine upload dist/* -u __token__ -p "$PYPI_TOKEN"
```
- Create and push tag: tszclient-py-vX.Y.Z.

Then the workflow:

Packages Python SDK + Python example into a zip:

zip -r "tszclient-py-${VERSION}.zip" \
  pkg/tszclient_py \
  examples/python-sdk-demo \
  -x '**/__pycache__/*' '*.pyc' '*.pyo'

Creates/updates a source repository Release for that tag and attaches the zip.

4. Local Testing of Release Scripts

You can run the release scripts locally for dry runs:

bash scripts/release/release_thyris-sz.sh --bump patch
bash scripts/release/release_tszclient-go.sh --bump patch
bash scripts/release/release_tszclient-py.sh --bump patch

Warning:

These scripts will create and push tags to origin unless you comment out the git push origin lines.
For true dry runs, temporarily comment or remove the git tag / git push origin lines and restore them afterwards.

5. Deleting Releases and Tags (for testing)

For testing purposes, you may want to delete a Release and/or a tag and re-run the pipeline.

5.1. Deleting a source repository Release

Go to Releases in the source repository repository.
Click the release you want to delete.
Use “Delete release” (this removes the Release and its assets, but not the tag).

5.2. Deleting tags

You may also want to remove the tag itself.

Locally:

git tag -d tszclient-go-v0.1.0

On remote (origin):

git push origin :refs/tags/tszclient-go-v0.1.0

Use tag deletion with care: removing tags may affect consumers relying on that version (e.g., Go module proxy or PyPI users, if mirrored).

After deleting the Release and tag, you can re-run the release workflow for that product to produce a fresh tag and assets.

6. Summary

Each product has its own version stream and tags.
The official artifacts are:
- thyris-sz: Git tag + source; binary currently built but not attached by default.
- tszclient-go: Go module source.example/thyris/safe-zone/pkg/tszclient-go, plus tszclient-go-X.Y.Z.zip (SDK + Go example) on source repository Releases.
- tszclient-py: PyPI package tszclient-py, plus tszclient-py-X.Y.Z.zip (SDK + Python example) on source repository Releases.
source repository’s auto-generated source archives always contain the full monorepo; SDK-only zips are explicitly packaged and attached by the workflow.

1. Versioning & Tagging​

1.1. Products and tags​

1.2. Bump types​

2. Official Artifacts per Product​

2.1. thyris-sz (service)​

2.2. tszclient-go (Go SDK)​

2.3. tszclient-py (Python SDK)​

3. Release Workflow (source repository Actions)​

3.1. How to run a release​

3.2. Product-specific behaviors​

thyris-sz​

tszclient-go (Go SDK)​

tszclient-py (Python SDK)​

4. Local Testing of Release Scripts​

5. Deleting Releases and Tags (for testing)​

5.1. Deleting a source repository Release​

5.2. Deleting tags​

6. Summary​

1. Versioning & Tagging

1.1. Products and tags

1.2. Bump types

2. Official Artifacts per Product

2.1. thyris-sz (service)

2.2. tszclient-go (Go SDK)

2.3. tszclient-py (Python SDK)

3. Release Workflow (source repository Actions)

3.1. How to run a release

3.2. Product-specific behaviors

thyris-sz

tszclient-go (Go SDK)

tszclient-py (Python SDK)

4. Local Testing of Release Scripts

5. Deleting Releases and Tags (for testing)

5.1. Deleting a source repository Release

5.2. Deleting tags

6. Summary