add more docs

Author: joao-r-reis

UPGRADE_GUIDE.md

@@ -0,0 +1,328 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# GoCQL Major Version Upgrade Guide
+
+This guide helps you migrate between major versions of the GoCQL driver. Each major version introduces significant changes that may require code modifications.
+
+## Available Upgrade Paths
+
+- [v1.x → v2.x](#upgrading-from-v1x-to-v2x)
+- [Future version upgrades will be documented here as they become available]
+
+---
+
+## Upgrading from v1.x to v2.x
+
+Version 2.0.0 introduced significant changes to the GoCQL driver. This section separates immediate breaking changes from deprecation notices to help you plan your migration.
+
+**Important:** The minimum Go version was raised to **Go 1.19** in v2.0.0.
+
+### Table of Contents
+
+- [Breaking Changes](#breaking-changes)
+  - [API Changes (Compilation Failures)](#api-changes-compilation-failures)
+  - [Behavioral Changes (Runtime Changes)](#behavioral-changes-runtime-changes)
+- [Migration Steps](#migration-steps)
+  - [Required Changes (All Users)](#required-changes-all-users)
+  - [Advanced Changes (Advanced Users Only)](#advanced-changes-advanced-users-only)
+- [Detailed Migration Examples](#detailed-migration-examples)
+- [Deprecation Notices](#deprecation-notices)
+
+---
+
+## Breaking Changes
+
+These changes will cause compilation failures or runtime behavior changes and must be addressed before upgrading to v2.0.0.
+
+### API Changes (Compilation Failures)
+
+These changes will cause your code to fail compilation and must be fixed immediately:
+
+#### 1. Import Path Change
+**Required for all users**
+
+```go
+// OLD (v1.x)
+import "github.com/gocql/gocql"
+
+// NEW (v2.x)
+import "github.com/apache/cassandra-gocql-driver/v2"
+```
+
+#### 2. Removed APIs
+**Action required if you use these APIs**
+
+- **`Session.SetTrace()`** → Use `Query.Trace()` or `Batch.Trace()` instead
+- **`ClusterConfig.ProtoVersion` values 1 and 2** → Use version 3+ only
+- **`SimpleRetryPolicy`** → Use `ExponentialBackoffRetryPolicy` or implement `RetryPolicy`
+
+### Behavioral Changes (Runtime Changes)
+
+These changes modify existing behavior and may require code updates:
+
+#### 1. Default Retry Policy
+- **Old:** No retries by default
+- **New:** `ExponentialBackoffRetryPolicy` with sensible defaults
+- **Impact:** Queries may now retry automatically on failures
+- **Action:** Review and adjust retry policies if needed
+
+#### 2. Connection Pool Behavior
+- **Change:** Improved connection pool management and recovery
+- **Impact:** Better performance but may change timing of reconnections
+- **Action:** Monitor application behavior, adjust pool settings if needed
+
+#### 3. Error Types
+- Some error types have been refined for better categorization
+- **Action:** Review error handling code, especially if you type-assert on specific error types
+
+---
+
+## Migration Steps
+
+### Required Changes (All Users)
+
+Follow these steps in order:
+
+#### Step 1: Update Go Version
+Ensure you're using **Go 1.19 or later**:
+```bash
+go version  # Should show 1.19 or higher
+```
+
+#### Step 2: Update Import Statements
+Replace all import statements:
+```bash
+# Using find/replace in your editor, or:
+find . -name "*.go" -exec sed -i 's|github.com/gocql/gocql|github.com/apache/cassandra-gocql-driver/v2|g' {} +
+```
+
+#### Step 3: Update go.mod
+```bash
+go mod edit -require=github.com/apache/cassandra-gocql-driver/v2@latest
+go mod edit -droprequire=github.com/gocql/gocql
+go mod tidy
+```
+
+#### Step 4: Fix Removed APIs
+Review compilation errors and apply these fixes:
+
+**SetTrace() Removal:**
+```go
+// OLD
+session.SetTrace(tracer)
+query := session.Query("SELECT ...")
+
+// NEW
+query := session.Query("SELECT ...").Trace(tracer)
+```
+
+**Unsupported Protocol Versions:**
+```go
+// OLD
+cluster.ProtoVersion = 2  // No longer supported
+
+// NEW
+cluster.ProtoVersion = 3  // Minimum supported version
+// or omit to auto-negotiate
+```
+
+#### Step 5: Test and Validate
+```bash
+go build ./...  # Check for compilation errors
+go test ./...   # Run your test suite
+```
+
+### Advanced Changes (Advanced Users Only)
+
+These changes only affect users of advanced features:
+
+#### Custom Retry Policies
+If you implemented custom retry policies:
+```go
+// Review the RetryPolicy interface - it may have changed
+// Test your custom implementation thoroughly
+```
+
+#### Custom Host Policies
+If you implemented custom host selection policies:
+```go
+// Verify your HostSelectionPolicy implementation
+// Check for interface changes
+```
+
+#### Low-level Connection Management
+If you used internal APIs or connection-level features:
+- Review all code for removed/changed internal APIs
+- Consider using supported public APIs instead
+- Test connection handling thoroughly
+
+---
+
+## Detailed Migration Examples
+
+### Example 1: Basic Application Migration
+
+**Before (v1.x):**
+```go
+package main
+
+import (
+    "github.com/gocql/gocql"
+    "log"
+)
+
+func main() {
+    cluster := gocql.NewCluster("127.0.0.1")
+    cluster.ProtoVersion = 2
+    session, err := cluster.CreateSession()
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer session.Close()
+
+    // Set global trace
+    session.SetTrace(gocql.NewTraceWriter(session, os.Stdout))
+    
+    query := session.Query("SELECT * FROM users WHERE id = ?", userID)
+    // ... rest of code
+}
+```
+
+**After (v2.x):**
+```go
+package main
+
+import (
+    "github.com/apache/cassandra-gocql-driver/v2"  // Updated import
+    "log"
+    "os"
+)
+
+func main() {
+    cluster := gocql.NewCluster("127.0.0.1")
+    cluster.ProtoVersion = 3  // Updated minimum version
+    session, err := cluster.CreateSession()
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer session.Close()
+
+    // Per-query trace instead of global
+    tracer := gocql.NewTraceWriter(session, os.Stdout)
+    query := session.Query("SELECT * FROM users WHERE id = ?", userID).
+        Trace(tracer)  // Trace per query
+    // ... rest of code
+}
+```
+
+### Example 2: Custom Retry Policy Migration
+
+**Before (v1.x):**
+```go
+// OLD - SimpleRetryPolicy no longer exists
+cluster.RetryPolicy = &gocql.SimpleRetryPolicy{NumRetries: 3}
+```
+
+**After (v2.x):**
+```go
+// NEW - Use ExponentialBackoffRetryPolicy or implement custom
+cluster.RetryPolicy = &gocql.ExponentialBackoffRetryPolicy{
+    MaxRetries:      3,
+    InitialInterval: time.Second,
+    MaxInterval:     30 * time.Second,
+}
+
+// OR implement your own:
+type MyRetryPolicy struct{}
+func (m *MyRetryPolicy) Attempt(q gocql.RetryableQuery) bool { /* implementation */ }
+func (m *MyRetryPolicy) GetRetryType(err error) gocql.RetryType { /* implementation */ }
+cluster.RetryPolicy = &MyRetryPolicy{}
+```
+
+### Example 3: Batch with Tracing Migration
+
+**Before (v1.x):**
+```go
+session.SetTrace(tracer)  // Global trace
+batch := session.Batch(gocql.LoggedBatch)
+batch.Query("INSERT INTO users (id, name) VALUES (?, ?)", id, name)
+err := session.ExecuteBatch(batch)
+```
+
+**After (v2.x):**
+```go
+// Per-batch trace
+batch := session.Batch(gocql.LoggedBatch).
+    Query("INSERT INTO users (id, name) VALUES (?, ?)", id, name).
+    Trace(tracer)  // Trace per batch
+err := batch.Exec()
+```
+
+---
+
+## Deprecation Notices
+
+The following features are deprecated but still functional in v2.x. Plan to migrate away from these in future releases:
+
+### Deprecated (Will be removed in v3.x)
+
+1. **`Session.ExecuteBatch()`** → Use `Batch.Exec()` fluent API
+2. **`Session.ExecuteBatchCAS()`** → Use `Batch.ExecCAS()` fluent API
+3. **`Session.MapExecuteBatchCAS()`** → Use `Batch.MapExecCAS()` fluent API
+
+**Migration Timeline:**
+- v2.x: Deprecated APIs work but emit warnings
+- v3.x: Deprecated APIs will be removed
+
+**Example Migration:**
+```go
+// DEPRECATED (still works in v2.x)
+batch := session.NewBatch(gocql.LoggedBatch)
+batch.Query("INSERT INTO users (id, name) VALUES (?, ?)", id, name)
+err := session.ExecuteBatch(batch)
+
+// RECOMMENDED (future-proof)
+err := session.Batch(gocql.LoggedBatch).
+    Query("INSERT INTO users (id, name) VALUES (?, ?)", id, name).
+    Exec()
+```
+
+---
+
+## Need Help?
+
+If you encounter issues during migration:
+
+1. **Check the [CHANGELOG.md](CHANGELOG.md)** for detailed changes
+2. **Review the [examples](example_test.go)** for updated usage patterns
+3. **Search [GitHub Issues](https://github.com/apache/cassandra-gocql-driver/issues)** for similar problems
+4. **Create a new issue** if you find bugs or need clarification
+
+## Version Compatibility Matrix
+
+| GoCQL Version | Go Version | Cassandra Version | Protocol Version |
+|---------------|------------|------------------|------------------|
+| v1.x          | 1.16+      | 2.1+             | 2, 3, 4         |
+| v2.x          | 1.19+      | 2.1+             | 3, 4, 5         |
+
+---
+
+*Last updated: [Current Date] for GoCQL v2.0.0*