# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/gonzo-docs/contributing/development-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.