fix: v5 follow-ups: Version() prefix, migration guide, release major guard

.github/workflows/initiate_release.yml

@@ -18,6 +18,27 @@ jobs:
         with:
           fetch-depth: 0 # gives the changelog generator access to all previous commits
 
+      # Go resolves a v2+ module only if go.mod carries the matching /vN suffix, so a major
+      # release tagged before the module path is migrated is unusable (see v5.0.0).
+      - name: Verify module path matches the requested major
+        env:
+          VERSION: ${{ github.event.inputs.version }}
+        run: |
+          requested="${VERSION#v}"
+          requested="${requested%%.*}"
+          module_path="$(sed -n 's/^module //p' go.mod)"
+          case "$module_path" in
+            */v[0-9]*) module_major="${module_path##*/v}" ;;
+            *) module_major=1 ;;
+          esac
+          expected="$requested"
+          [ "$expected" = "0" ] && expected=1
+          if [ "$module_major" != "$expected" ]; then
+            echo "::error::go.mod declares '$module_path' (major v$module_major) but the release is $VERSION."
+            echo "::error::Migrate go.mod and every self-import to .../v$requested first, then re-run this workflow."
+            exit 1
+          fi
+
       - name: Update CHANGELOG.md and version.go, then push release branch
         env:
           VERSION: ${{ github.event.inputs.version }}

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-## [5.1.0](https://github.com/GetStream/getstream-go/compare/v5.0.0...v5.1.0) (2026-07-24)
+## [5.1.0](https://github.com/GetStream/getstream-go/compare/v4.2.2...v5.1.0) (2026-07-24)
 
 
 ### Features
@@ -15,7 +15,9 @@ All notable changes to this project will be documented in this file. See [standa
 
 * align go module path with the v5 major version ([#130](https://github.com/GetStream/getstream-go/issues/130)) ([e4b36ff](https://github.com/GetStream/getstream-go/commit/e4b36ffa6a05e81f83277c90f59d3cb8f20383e2))
 
-## [5.0.0](https://github.com/GetStream/getstream-go/compare/v4.2.2...v5.0.0) (2026-07-15)
+## 5.0.0 (2026-07-15)
+
+> Withdrawn. These changes shipped in 5.1.0. See [MIGRATION_v4_to_v5.md](MIGRATION_v4_to_v5.md).
 
 
 ### ⚠ BREAKING CHANGES

MIGRATION_v4_to_v5.md

@@ -0,0 +1,77 @@
+# Migration Guide: v4 → v5
+
+v5 is a small release. The import path changes, four response fields that the API no longer returns are gone, and `CheckResponse` can no longer be compared with `==`. Everything else is additive, so most codebases only need to update the import path.
+
+## Start at v5.1.0
+
+v5.1.0 is the first v5 release. v5.0.0 was withdrawn, and everything in it is included in v5.1.0.
+
+## Installation
+
+```bash
+go get github.com/GetStream/getstream-go/v5
+```
+
+Update all import paths in your code:
+
+```go
+// Before
+import "github.com/GetStream/getstream-go/v4"
+
+// After
+import "github.com/GetStream/getstream-go/v5"
+```
+
+## Breaking Changes
+
+### Removed fields
+
+These fields were dropped from the API spec and have no replacement. They were never populated in a way applications could rely on.
+
+| Type | Field | JSON |
+| --- | --- | --- |
+| `AppResponseFields` | `ModerationAudioFileEnabled` | `moderation_audio_file_enabled` |
+| `ModerationDashboardPreferences` | `AnalyzeMaxImageSizeBytes` | `analyze_max_image_size_bytes` |
+| `ModerationDashboardPreferences` | `AnalyzeMaxKeyframeSizeBytes` | `analyze_max_keyframe_size_bytes` |
+| `ModerationDashboardPreferences` | `WebhookHeaderClientRequestIDKey` | `webhook_header_client_request_id_key` |
+
+### `CheckResponse` is no longer comparable
+
+`CheckResponse` gained `TriggeredRules []TriggeredRuleResponse`, which lists every rule a moderation check triggered. A struct containing a slice is not comparable in Go, so `==` on it no longer compiles:
+
+```go
+// v4: compiled
+if got == want { ... }
+
+// v5: compile error
+// invalid operation: got == want (struct containing []getstream.TriggeredRuleResponse cannot be compared)
+if reflect.DeepEqual(got, want) { ... }
+```
+
+This propagates to anything embedding it, most commonly `StreamResponse[CheckResponse]`. Field-by-field comparison works too and is usually what you want in tests.
+
+The singular `TriggeredRule *TriggeredRuleResponse` is still present and still populated with the first triggered rule, so existing reads keep working. Prefer `TriggeredRules` for new code: it is the only field that surfaces content, user, and call rules together.
+
+## New in v5
+
+- `ChatClient.GetChannel(ctx, type, id, request)` and `Channels.Get(ctx, request)`: fetch channel state without a `GetOrCreate` write.
+- `CheckResponse.TriggeredRules`: all rules triggered by a moderation check, with their resolved actions.
+- `ModerationCallResponse`: the moderation call payload has its own type. The Video `CallResponse` is unchanged.
+- Feeds translation: `TranslateActivity`, `TranslateComment`, `I18n` on activity and comment responses, plus `Language` and `TranslateText` parameters on the feeds read endpoints.
+- Activity shares: `QueryActivityShares`, `ShareResponse`, `FeedsShareResponse`.
+- `WithRetry(RetryConfig{...})`: opt-in retry for rate-limited and transport-failed requests (v5.1.0).
+- `WithLogBodies(true)` and structured client log events with secret redaction (v5.1.0).
+
+## Verifying your upgrade
+
+The removals and the comparability change are all compile-time failures, so the compiler finds every affected line for you:
+
+```bash
+go build ./... && go vet ./...
+```
+
+## Getting Help
+
+- [Stream documentation](https://getstream.io/docs/)
+- [GitHub Issues](https://github.com/GetStream/getstream-go/issues)
+- [Stream support](https://getstream.io/contact/support/)

README.md

@@ -25,6 +25,11 @@
 
 If you are currently using [`stream-chat-go`](https://github.com/GetStream/stream-chat-go), we have a detailed migration guide with side-by-side code examples for common Chat use cases. See the [Migration Guide](docs/migration-from-stream-chat-go/README.md).
 
+## Upgrading from an older major?
+
+- [v4 → v5](MIGRATION_v4_to_v5.md): new import path, four removed response fields, `CheckResponse` no longer comparable.
+- [v3 → v4](MIGRATION_v3_to_v4.md): OpenAPI-aligned type renaming.
+
 ## **Quick Links**
 
 - [Register](https://getstream.io/chat/trial/) to get an API key for Stream

version.go

@@ -4,9 +4,10 @@ const (
 	versionName = "v5.1.0"
 )
 
-// Version returns the version of the library.
+// Version returns the version of the library. versionName is written by the release
+// workflow and already carries the leading "v".
 func Version() string {
-	return "v" + versionName
+	return versionName
 }
 
 func versionHeader() string {