# Development Setup

Get your development environment ready to contribute to Gonzo. This guide covers everything from prerequisites to running your first build.

### Prerequisites

#### Required Software

**Go Programming Language**:

* Version: 1.21 or higher
* Download: <https://golang.org/dl/>
* Installation guide: <https://golang.org/doc/install>

```bash
# Verify Go installation
go version
# Should show: go version go1.21.x or higher
```

**Git**:

* Version: 2.0 or higher
* Download: <https://git-scm.com/downloads>

```bash
# Verify Git installation
git --version
```

**Make** (optional but recommended):

* Usually pre-installed on macOS/Linux
* Windows: Install via Chocolatey or use Git Bash

```bash
# Verify Make installation
make --version
```

#### Recommended Tools

**Code Editor**:

* VS Code with Go extension
* GoLand
* Vim/Neovim with vim-go
* Any editor with Go support

**Terminal**:

* Modern terminal with good Unicode support
* Recommendations: iTerm2, Alacritty, Windows Terminal

**Additional Tools**:

```bash
# Code formatting
go install golang.org/x/tools/cmd/goimports@latest

# Linting
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Testing
go install gotest.tools/gotestsum@latest
```

### Getting the Source Code

#### Fork the Repository

1. Go to <https://github.com/control-theory/gonzo>
2. Click "Fork" button (top right)
3. This creates your own copy of the repository

#### Clone Your Fork

```bash
# Clone your fork
git clone https://github.com/YOUR-USERNAME/gonzo.git
cd gonzo

# Add upstream remote
git remote add upstream https://github.com/control-theory/gonzo.git

# Verify remotes
git remote -v
# Should show:
# origin    https://github.com/YOUR-USERNAME/gonzo.git (fetch)
# origin    https://github.com/YOUR-USERNAME/gonzo.git (push)
# upstream  https://github.com/control-theory/gonzo.git (fetch)
# upstream  https://github.com/control-theory/gonzo.git (push)
```

#### Sync with Upstream

Keep your fork up to date:

```bash
# Fetch latest changes from upstream
git fetch upstream

# Switch to main branch
git checkout main

# Merge upstream changes
git merge upstream/main

# Push to your fork
git push origin main
```

### Project Structure

Understanding the codebase:

```
gonzo/
├── cmd/
│   └── gonzo/              # Application entry point
│       ├── main.go         # Main function
│       ├── app.go          # Application setup
│       ├── extractors.go   # Data extraction
│       └── processing.go   # Log processing
│
├── internal/               # Private application code
│   ├── tui/               # Terminal UI (Bubble Tea)
│   │   ├── model.go       # Application model
│   │   ├── update.go      # Update logic
│   │   ├── view.go        # View rendering
│   │   ├── components.go  # UI components
│   │   ├── charts.go      # Chart rendering
│   │   ├── tables.go      # Table components
│   │   ├── modals.go      # Modal dialogs
│   │   ├── navigation.go  # Navigation handling
│   │   ├── formatting.go  # Text formatting
│   │   ├── severity.go    # Severity handling
│   │   ├── styles.go      # UI styles
│   │   └── drain3_manager.go # Drain3 integration
│   │
│   ├── analyzer/          # Log analysis
│   │   ├── otlp.go       # OTLP analysis
│   │   └── text.go       # Text analysis
│   │
│   ├── memory/            # Data storage
│   │   └── frequency.go   # Frequency tracking
│   │
│   ├── otlplog/          # OTLP handling
│   │   ├── converter.go   # Log conversion
│   │   └── detector.go    # Format detection
│   │
│   ├── drain3/           # Log clustering
│   │   └── impl.go       # Drain3 implementation
│   │
│   ├── ai/               # AI integration
│   │   └── openai.go     # OpenAI API
│   │
│   ├── output/           # Output handlers
│   │   └── stdout.go     # Standard output
│   │
│   └── reader/           # Input readers
│       └── stdin.go      # Standard input
│
├── examples/             # Example files
│   ├── config.yml       # Sample config
│   └── formats/         # Custom formats
│
├── docs/                # Documentation
├── Makefile            # Build automation
├── go.mod              # Go module
└── go.sum              # Dependencies
```

### Building Gonzo

#### Quick Build

```bash
# Build using Make (recommended)
make build

# Binary created at: ./bin/gonzo
./bin/gonzo --version
```

#### Manual Build

```bash
# Build without Make
go build -o bin/gonzo ./cmd/gonzo

# Run
./bin/gonzo --version
```

#### Development Build

```bash
# Build with all checks
make dev

# This runs:
# - go fmt (format code)
# - go vet (check for issues)
# - go test (run tests)
# - go build (compile binary)
```

#### Build for All Platforms

```bash
# Cross-compile for multiple platforms
make cross-build

# Creates binaries for:
# - Linux (amd64, arm64)
# - macOS (amd64, arm64)
# - Windows (amd64)
```

### Running Tests

#### Unit Tests

```bash
# Run all tests
make test

# Or with go directly
go test ./...

# Verbose output
go test -v ./...

# Specific package
go test ./internal/analyzer/...
```

#### Race Detection

```bash
# Detect race conditions
make test-race

# Or with go directly
go test -race ./...
```

#### Coverage Report

```bash
# Generate coverage report
go test -coverprofile=coverage.out ./...

# View coverage in browser
go tool cover -html=coverage.out
```

#### Integration Tests

```bash
# Run integration tests
make test-integration

# Or with tags
go test -tags=integration ./...
```

### Running Gonzo in Development

#### Basic Run

```bash
# Build and run
make build
./bin/gonzo -f examples/sample.log

# Or run directly without building
go run ./cmd/gonzo -f examples/sample.log
```

#### With Sample Data

```bash
# Run demo with sample logs
make demo

# This generates sample logs and runs Gonzo
```

#### Testing Features

**Test file input**:

```bash
# Create test log file
cat > test.log << 'EOF'
{"level":"info","msg":"Test 1"}
{"level":"error","msg":"Test 2"}
{"level":"warn","msg":"Test 3"}
EOF

# Run Gonzo
./bin/gonzo -f test.log
```

**Test stdin**:

```bash
# Pipe logs to Gonzo
echo '{"level":"info","msg":"Hello"}' | ./bin/gonzo
```

**Test follow mode**:

```bash
# In terminal 1
./bin/gonzo -f /tmp/live.log --follow

# In terminal 2
while true; do 
  echo "{\"level\":\"info\",\"msg\":\"Log $(date)\"}" >> /tmp/live.log
  sleep 1
done
```

**Test OTLP receiver**:

```bash
# Start with OTLP enabled
./bin/gonzo --otlp-enabled

# In another terminal, send test log
curl -X POST http://localhost:4318/v1/logs \
  -H "Content-Type: application/json" \
  -d '{"resourceLogs":[{"scopeLogs":[{"logRecords":[{"body":{"stringValue":"test"}}]}]}]}'
```

### Development Workflow

#### 1. Create a Feature Branch

```bash
# Sync with upstream first
git fetch upstream
git checkout main
git merge upstream/main

# Create feature branch
git checkout -b feature/my-awesome-feature
```

#### 2. Make Changes

```bash
# Edit files
vim internal/tui/model.go

# Format code
go fmt ./...

# Or use goimports
goimports -w .
```

#### 3. Test Changes

```bash
# Run tests
make test

# Build and test manually
make build
./bin/gonzo -f test.log
```

#### 4. Commit Changes

```bash
# Stage changes
git add .

# Commit with meaningful message
git commit -m "feat: add awesome feature

Detailed description of what this feature does and why.

Closes #123"
```

#### 5. Push to Your Fork

```bash
# Push feature branch to your fork
git push origin feature/my-awesome-feature
```

#### 6. Create Pull Request

1. Go to your fork on GitHub
2. Click "Compare & pull request"
3. Fill out PR template
4. Submit pull request

### Code Style

#### Formatting

```bash
# Format all Go code
go fmt ./...

# Or use goimports (better)
goimports -w .
```

#### Linting

```bash
# Run golangci-lint
golangci-lint run

# Fix auto-fixable issues
golangci-lint run --fix
```

#### Code Conventions

**Naming**:

* Use camelCase for variables and functions
* Use PascalCase for exported names
* Keep names short but descriptive
* Avoid abbreviations unless common

**Comments**:

```go
// Good: Concise description
// ParseLog parses a log line and returns structured data.
func ParseLog(line string) (*Log, error) {
    // Implementation
}

// Bad: Redundant or missing
func ParseLog(line string) (*Log, error) {
    // Implementation
}
```

**Error Handling**:

```go
// Good: Wrap errors with context
if err != nil {
    return fmt.Errorf("failed to parse log: %w", err)
}

// Bad: Lose error context
if err != nil {
    return err
}
```

### Debugging

#### Using Delve

```bash
# Install Delve debugger
go install github.com/go-delve/delve/cmd/dlv@latest

# Debug Gonzo
dlv debug ./cmd/gonzo -- -f test.log

# In Delve:
# (dlv) break main.main
# (dlv) continue
# (dlv) next
# (dlv) print variableName
```

#### Logging Debug Info

```bash
# Run with verbose flag
./bin/gonzo -v -f test.log 2> debug.log

# Check debug output
tail -f debug.log
```

#### VS Code Debug Configuration

Create `.vscode/launch.json`:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Gonzo",
      "type": "go",
      "request": "launch",
      "mode": "debug",
      "program": "${workspaceFolder}/cmd/gonzo",
      "args": ["-f", "test.log"],
      "env": {},
      "showLog": true
    },
    {
      "name": "Debug Gonzo with OTLP",
      "type": "go",
      "request": "launch",
      "mode": "debug",
      "program": "${workspaceFolder}/cmd/gonzo",
      "args": ["--otlp-enabled"],
      "env": {},
      "showLog": true
    }
  ]
}
```

### Common Development Tasks

#### Adding a New Feature

1. **Plan the feature**
   * Open an issue to discuss
   * Get feedback from maintainers
   * Design the implementation
2. **Implement the feature**
   * Create feature branch
   * Write code following style guide
   * Add tests for new functionality
   * Update documentation
3. **Test thoroughly**
   * Unit tests
   * Integration tests
   * Manual testing
4. **Submit for review**
   * Create pull request
   * Address review comments
   * Wait for approval

#### Fixing a Bug

1. **Reproduce the bug**
   * Create minimal test case
   * Document steps to reproduce
2. **Write a failing test**
   * Test should fail before fix
   * Test should pass after fix
3. **Fix the bug**
   * Make minimal changes
   * Ensure test passes
4. **Submit fix**
   * Reference issue in commit
   * Include test in PR

#### Updating Dependencies

```bash
# Update all dependencies
go get -u ./...

# Tidy dependencies
go mod tidy

# Verify everything works
make test
```

### Performance Profiling

#### CPU Profiling

```bash
# Build with profiling
go build -o bin/gonzo ./cmd/gonzo

# Run with CPU profiling
./bin/gonzo -f large.log -cpuprofile=cpu.prof

# Analyze profile
go tool pprof cpu.prof
# Commands: top, list, web
```

#### Memory Profiling

```bash
# Run with memory profiling
./bin/gonzo -f large.log -memprofile=mem.prof

# Analyze profile
go tool pprof mem.prof
```

#### Benchmarking

```bash
# Run benchmarks
go test -bench=. ./...

# With memory stats
go test -bench=. -benchmem ./...

# Specific benchmark
go test -bench=BenchmarkParsing ./internal/analyzer/
```

### Troubleshooting Development Issues

#### Build Fails

**Dependency issues**:

```bash
# Clean module cache
go clean -modcache

# Re-download dependencies
go mod download

# Rebuild
make build
```

**Version mismatch**:

```bash
# Check Go version
go version

# Should be 1.21 or higher
# Update if needed
```

#### Tests Fail

**Race conditions**:

```bash
# Run with race detector
go test -race ./...

# Fix any race conditions found
```

**Flaky tests**:

* Run tests multiple times
* Check for timing dependencies
* Use proper synchronization

#### IDE Issues

**VS Code Go extension problems**:

```bash
# Reinstall Go tools
# Command Palette: Go: Install/Update Tools
```

**Gopls issues**:

```bash
# Clean gopls cache
rm -rf ~/Library/Caches/gopls  # macOS
rm -rf ~/.cache/gopls          # Linux
```

### Getting Help

#### Resources

* **GitHub Issues**: Ask questions, report bugs
* **GitHub Discussions**: General discussions
* **Code Review**: Learn from PR feedback
* **Documentation**: Read existing docs thoroughly

#### Communication

* **Be respectful**: Follow Code of Conduct
* **Be patient**: Maintainers are volunteers
* **Be clear**: Provide context and details
* **Be helpful**: Help others when you can

### Next Steps

Now that your development environment is set up:

1. **Read the codebase**: Familiarize yourself with the structure
2. **Pick an issue**: Look for "good first issue" labels
3. **Make a change**: Start with something small
4. **Submit a PR**: Get feedback and iterate

**Related Documentation**:

* Contribution Guidelines - Detailed contribution process
* Community - How to engage with the community
* Architecture Overview - Understanding the codebase

{% hint style="success" %}
**Ready to contribute?** Check out [open issues](https://github.com/control-theory/gonzo/issues) labeled "good first issue" to get started!
{% endhint %}

```bash
```