GitHub Tag Format for Multi-Module Go Repository

[renuka-fernando]

Problem Statement

Our repository is a multi-module Go monorepo with several Go modules located in subdirectories:

api-platform/
├── sdk/go.mod                    # module github.com/wso2/api-platform/sdk
├── gateway/
│   ├── gateway-controller/go.mod
│   ├── policy-engine/go.mod
│   ├── gateway-builder/go.mod
│   └── policies/
│       ├── ratelimit/v0.1.0/go.mod
│       ├── api-key-auth/v0.1.0/go.mod
│       └── ... (20+ policy modules)
├── platform-api/src/go.mod
└── sts/go.mod

The Issue with Current Tag Format

We currently use tags like:

• gateway-v0.2.0
• platform-api-v0.0.2
• ai-gateway-v0.2.0

This format does NOT work with Go's module system for modules that need to be imported as public dependencies.

Why This Matters: The SDK Module

The sdk module (github.com/wso2/api-platform/sdk) is designed to be imported by:

1. Internal policies within our repository
2. External/third-party policy developers who want to build custom policies

For external developers to import the SDK using standard Go tooling:

import "github.com/wso2/api-platform/sdk"

And run:

go get github.com/wso2/api-platform/sdk@v0.3.0

Go requires the tag to match the module path: sdk/v0.3.0

Go Module Versioning Rules for Subdirectories

From the Go Modules Reference:

If a module is defined in a subdirectory within the repository, that is, the module subdirectory portion of the module path is not empty, then each tag name must be prefixed with the module subdirectory, followed by a slash. For example, the module golang.org/x/tools/gopls is defined in the gopls subdirectory of the repository with root path golang.org/x/tools. The version v0.4.0 of that module must have the tag named gopls/v0.4.0 in that repository.

Current Tags Analysis

Tag	Format	Works with go get?
sdk/v0.3.0	<module-path>/vX.Y.Z	Yes
gateway-v0.2.0	<name>-vX.Y.Z	No
platform-api-v0.0.2	<name>-vX.Y.Z	No
helm-gateway-0.2.0	<name>-X.Y.Z	N/A (not a Go module)

Proposed Solution

For Public Go Modules (SDK)

Use the Go-required format: <module-path>/vX.Y.Z

sdk/v0.3.0          # Already created - works with go get
sdk/v0.4.0          # Future releases

For Internal/Non-Importable Components

We have two options:

Option A: Keep Current Format

Continue using <component>-vX.Y.Z for components that are NOT meant to be imported as Go modules:

gateway-v0.2.0           # Docker images, Helm charts reference
platform-api-v0.0.2      # Docker images reference
helm-gateway-0.2.0       # Helm chart versioning
gateway-operator-0.2.0   # Operator versioning

Pros:

• No migration needed for existing tooling
• Clear distinction between "Go module tags" and "release tags"

Cons:

• Two different tag formats in the repository (inconsistent)
• Confusing for contributors

Option B: Use Slash Format for Everything (Recommended)

sdk/v0.3.0               # Go module (already created)
gateway/v0.2.0           # Docker images, Helm charts reference
platform-api/v0.0.2      # Docker images reference
helm/gateway/v0.2.0      # Helm chart versioning
gateway-operator/v0.2.0  # Operator versioning

Pros:

• Consistent format across all tags
• Follows Go module conventions universally
• Future-proof if any component becomes a public Go module
• All components are still at 0.x.x - now is the best time to standardize before 1.0.0

Cons:

• Requires updating CI/CD pipelines (one-time effort)

Recommendation

Adopt Option B: Use slash format (<component>/vX.Y.Z) for all tags.

Since all components are still at 0.x.x, migration cost is minimal. Standardizing now avoids:

• Confusing contributors with two different conventions
• Breaking changes later when we reach 1.0.0
• Inconsistent tooling and documentation

Tag Format Summary

Component Type	Current	New Format
SDK (Go module)	sdk/v0.3.0	sdk/vX.Y.Z
Gateway	gateway-v0.2.0	gateway/vX.Y.Z
Platform API	platform-api-v0.0.2	platform-api/vX.Y.Z
Helm charts	helm-gateway-0.2.0	helm/gateway/vX.Y.Z
Operators	gateway-operator-0.2.0	gateway-operator/vX.Y.Z

References

• Go Modules Reference - Version Control Systems
• Go Blog - Module Version Numbering
• Existing tag: sdk/v0.3.0

[malinthaprasan]

+1 for the new format

[Krishanx92]

+1