Examples
Go SDKs with explicit build and release flow
A Go SDK contract that keeps build, lint, and release guidance obvious.
copynew usersbasicstable2026-05-30
Recommended next
Typical signals
- native host execution context is explicit
- Go module dependencies are explicit
- release checks stay separate from release versioning
- notes explain the command order for release work
Why it matters
- it turns a repo pattern into something humans, CI, and agents can read the same way
- it makes the next command obvious instead of implied by README drift
- it keeps readiness, setup, and execution explainable in receipts and diagnostics
Example contract
This example treats the SDK as a product surface: the core loop stays short, and the release path is documented in the task notes.
ota.yamlyaml
version: 1project: name: go-sdk description: Go SDK with explicit release and changelog flow type: librarymetadata: ota: minimum_version: "1.6.26" team: sdk owner: ota repo_class: go-sdktoolchains: go: version: "1.26.0"execution: default_context: host contexts: host: backend: nativetools: golangci-lint: version: "1.64.8" acquisition: provider: command shell: sh run: go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.64.8 docker: '*'tasks: setup: internal: true description: Download Go module dependencies notes: | Use this first after cloning or when module dependencies change. category: setup prepare: kind: dependency_hydration medium: package_dependencies source: kind: go_modules cwd: . requirements: toolchains: - go effects: network: true network_kind: dependency_hydration build: description: Build the Go SDK notes: | Use this to confirm the Go package still builds cleanly. category: build command: exe: go args: - build - ./... depends_on: - setup test: description: Run the Go test suite notes: | Use this for the standard Go unit test pass. category: test command: exe: go args: - test - ./... depends_on: - setup vet: description: Run Go vet notes: | Use this for static analysis of suspicious Go code patterns. category: test command: exe: go args: - vet - ./... depends_on: - setup lint: description: Run golangci-lint notes: | Use this for the full lint gate before merging changes. category: test command: exe: golangci-lint args: - run - ./... depends_on: - setup requirements: tools: golangci-lint: "*" release:check: description: Run the release verification suite notes: | Use this as the release gate before tagging or pushing a release. This task composes build, test, vet, and lint. `ota run release:check` Typical flow: ota run release:check ota run release:version --version x.y.z category: release aggregate: tasks: - build - test - vet - lint release:version: description: Bump the SDK version and promote the changelog notes: | Use this when preparing a new release version. `ota run release:version --version 0.2.1` Run `ota run release:check` before this task. This updates the SDKVersion constant in config.go and promotes the Unreleased changelog entry into the new version section. The task forwards `--version` into `OTA_INPUT_VERSION`. category: release depends_on: - build - test - vet - lint script: | version="${OTA_INPUT_VERSION}" if [ -z "$version" ]; then echo "Usage: ota run release:version --version <x.y.z>" >&2 exit 1 fi if ! printf '%s' "$version" | grep -Eq '^[0-9]+.[0-9]+.[0-9]+([.-][0-9A-Za-z.-]+)?(+[0-9A-Za-z.-]+)?$'; then echo "Invalid semver version: $version" >&2 exit 1 fi release_date="$(date -u +%F)" perl -0pi -e 's/const SDKVersion = "[^"]+"/const SDKVersion = "'$version'"/' config.go echo "Updated config.go SDKVersion to $version" if grep -Eq '^## ['"$version"'] - ' CHANGELOG.md; then echo "CHANGELOG.md already contains release $version" exit 0 fi if ! grep -Eq '^## [Unreleased]$' CHANGELOG.md; then echo "CHANGELOG.md is missing the Unreleased heading" >&2 exit 1 fi perl -0pi -e 's/^## [Unreleased] /## [Unreleased] ## ['"$version"'] - '"$release_date"' /m' CHANGELOG.md echo "Updated CHANGELOG.md for $version" inputs: version: description: New release version to apply to config.go required: trueTask notes
Task notes stay close to the task they explain.
Use notes: when a task needs short operator guidance, not long prose.
Keep each note command-oriented and specific to the task that follows it.
For release tasks, put the sequence and the required input flag in the note itself.