# Known Issues and Limitations - Go SDK Packaging (Story 1.8)

## Critical Issues

### 1. Incomplete go.sum (BLOCKER)

**Status:** ❌ UNRESOLVED - Blocks production use

**Problem:** The go.sum file only contains 6 lines with checksums for:
- github.com/google/uuid v1.6.0
- go.opentelemetry.io/otel v1.27.0  
- go.opentelemetry.io/otel/sdk v1.27.0

**Missing Dependencies:**
- All OTLP exporters (otlpmetrichttp, otlptracehttp, otlploghttp)
- All transitive dependencies
- Complete dependency graph

**Root Cause:** TLS certificate issues in the development environment prevent `go mod tidy` and `go mod download` from completing successfully.

**Impact:**
- `go get` will fail for end users
- Checksum verification will fail
- Module cannot be properly distributed

**Resolution Required:**
1. Fix TLS certificate configuration in environment
2. Run `go mod download` successfully
3. Run `go mod tidy` to generate complete go.sum
4. Verify all transitive dependencies are captured
5. Commit updated go.sum

**Workaround:** None. This must be fixed before any distribution.

---

### 2. Untested Code (CRITICAL)

**Status:** ❌ UNRESOLVED - Code quality risk

**Problem:** Due to TLS certificate issues, the following were never executed:
- `go build` - code never compiled
- `go test` - test suite never run
- Import path validation
- Syntax verification

**Impact:**
- No confidence that module imports work correctly
- Potential syntax errors or typos undetected
- Test failures unknown
- Circular dependency risks unverified

**Resolution Required:**
1. Fix TLS certificate issues
2. Run: `go build ./...`
3. Run: `go test -v ./...`
4. Run: `go test -race ./...`
5. Verify all tests pass
6. Fix any discovered issues

---

### 3. Nested Module Tagging (RESOLVED)

**Status:** ✅ FIXED

**Problem:** Initial implementation used tag `v0.1.0` instead of `mca-prototype/mca-sdk-go/v0.1.0`.

**Why It's Critical:** Go modules in subdirectories require the full path prefix in the git tag. Without it, `go get` cannot resolve the module version.

**Resolution:** Tag corrected to `mca-prototype/mca-sdk-go/v0.1.0`.

**Verification:**
```bash
git tag -l | grep mca-prototype
# Output: mca-prototype/mca-sdk-go/v0.1.0
```

---

## Documentation Issues

### 4. pkg.go.dev Indexing (Informational)

**Status:** ⚠️ LIMITATION

**Problem:** Acceptance criteria mentioned verifying godoc via pkg.go.dev. This repository is private on GitLab.

**Reality:** pkg.go.dev cannot index private GitLab repositories without complex authentication proxy setup.

**Impact:** Public documentation hosting is not available out-of-the-box.

**Alternatives:**
- Use `go doc` locally
- Set up internal godoc server
- Use GitLab's built-in Go package registry documentation (if available)

---

### 5. Stale Documentation References (RESOLVED)

**Status:** ✅ FIXED

**Problem:** EXAMPLES.md and TESTING_WORKBENCH.md contained old `github.com/baptisthealth/mca-sdk-go` import paths.

**Resolution:** All documentation updated to use correct GitLab module path.

---

## Development Workflow Issues

### 6. Replace Directive in Examples

**Status:** ⚠️ DOCUMENTED

**Problem:** Example's go.mod uses:
```go
replace gitlab.com/bhsf/ai_ml/model-monitoring/sdk/mca-prototype/mca-sdk-go => ../../mca-sdk-go
```

**Impact:**
- Example cannot validate real module fetching
- Users copying the example will have issues if they don't have the full repo structure

**Resolution:**
- Added comments explaining this is for development only
- Created README.md with instructions for production use
- Documented how to remove replace directive

---

### 7. Manual Version Management

**Status:** ⚠️ BY DESIGN

**Problem:** Version is hardcoded in version.go and must be manually kept in sync with git tags.

**Rationale:** 
- Git tags are source of truth for Go module versioning
- version.go constant is for runtime telemetry attribution
- Go has no built-in version injection at compile time (without custom build flags)

**Process:** 
1. Update version.go constant
2. Create matching git tag with full path prefix
3. Push both commit and tag together

**Documentation:** Added detailed comments to version.go explaining this requirement.

---

### 8. Missing CI/CD Integration

**Status:** ❌ NOT IMPLEMENTED

**Problem:** No CI/CD automation for:
- Go module versioning
- Test execution
- Static analysis (golangci-lint)
- go.sum verification
- Build validation

**Impact:**
- Packaging process is entirely manual
- No automated quality gates
- Risk of shipping broken builds

**Recommendation:** Add to .gitlab-ci.yml:
```yaml
go-sdk-test:
  stage: test
  script:
    - cd mca-prototype/mca-sdk-go
    - go mod verify
    - go build ./...
    - go test -v -race ./...
    - golangci-lint run
  only:
    - branches
    - tags
```

---

## Module Distribution Issues

### 9. Verbose Module Path

**Status:** ⚠️ BY DESIGN

**Problem:** Module path is extremely verbose:
```
gitlab.com/bhsf/ai_ml/model-monitoring/sdk/mca-prototype/mca-sdk-go
```

**Root Cause:** Go SDK lives in a subdirectory of a monorepo containing Python, Java, and Node.js SDKs.

**Impact:**
- Longer import statements
- More complex for users to remember/type

**Alternatives:**
1. Create separate repository for Go SDK (cleaner but more repos to manage)
2. Move Go SDK to repo root (would require restructuring entire repo)
3. Keep current structure (accepted compromise)

**Decision:** Keeping current structure. Verbosity is acceptable trade-off for monorepo benefits.

---

### 10. Private Repository Authentication

**Status:** ⚠️ USER RESPONSIBILITY

**Problem:** Users need GitLab authentication to download the module.

**Impact:** Cannot simply run `go get` without authentication setup.

**User Setup Required:**

**Option 1: Personal Access Token**
```bash
git config --global url."https://oauth2:${GITLAB_TOKEN}@gitlab.com/".insteadOf "https://gitlab.com/"
export GOPRIVATE=gitlab.com/bhsf
```

**Option 2: .netrc File**
```bash
cat >> ~/.netrc << EOF
machine gitlab.com
login oauth2
password ${GITLAB_TOKEN}
EOF
chmod 600 ~/.netrc
```

**Option 3: SSH Keys**
```bash
git config --global url."git@gitlab.com:".insteadOf "https://gitlab.com/"
export GOPRIVATE=gitlab.com/bhsf
```

**Documentation:** Should be added to README.md installation section.

---

## Testing and Validation

### 11. Semantic Versioning Continuity

**Status:** ✅ VERIFIED

**Concern:** Jumping from 0.8.8 to 0.1.0 could break semantic versioning.

**Verification:**
```bash
git tag -l | grep -i "go"
# Output: mca-prototype/mca-sdk-go/v0.1.0
```

**Finding:** No prior Go SDK git tags exist. The 0.8.8 version was only in code (for parity tracking with Python SDK), never as an actual module release tag. Therefore, v0.1.0 is legitimately the first release, and there is no semantic versioning violation.

---

## Action Items

### Before Any Distribution

**MUST FIX (Blockers):**
- [ ] Fix TLS certificate issues in environment
- [ ] Run `go mod download` successfully  
- [ ] Run `go mod tidy` to generate complete go.sum
- [ ] Run `go build ./...` and verify success
- [ ] Run `go test -v ./...` and verify all tests pass
- [ ] Commit updated go.sum with full dependencies

**SHOULD FIX (High Priority):**
- [ ] Add CI/CD pipeline for Go SDK testing
- [ ] Add authentication setup instructions to README.md
- [ ] Create script to validate tag/version consistency
- [ ] Add pre-push hook to verify go.sum is complete

**NICE TO HAVE (Low Priority):**
- [ ] Set up internal godoc server
- [ ] Create separate example repository without replace directive
- [ ] Consider moving Go SDK to separate repo for cleaner module path

---

## Distribution Checklist

Before pushing to GitLab and announcing availability:

1. ✅ Git tag created with correct prefix format
2. ❌ go.sum complete with all transitive dependencies
3. ❌ Code compiles successfully
4. ❌ All tests pass
5. ✅ All documentation updated with correct module path
6. ✅ version.go matches git tag
7. ⚠️ Authentication instructions documented (TODO: add to README)
8. ❌ CI/CD pipeline validates builds

**Overall Status: NOT READY FOR DISTRIBUTION**

---

## Development Environment Notes

The development environment has TLS certificate validation issues that prevent downloading Go modules from proxy.golang.org and sum.golang.org. This is an infrastructure issue, not a code issue.

**Error:**
```
tls: failed to verify certificate: x509: certificate signed by unknown authority
```

**Attempted Workarounds:**
- `GOINSECURE=proxy.golang.org` (did not help)
- `GOPRIVATE` settings (not applicable for public dependencies)

**Required Fix:** Environment must have proper TLS certificates installed or Go must be configured to work with the environment's certificate authority.
