dance-lessons-coach/scripts/cicd/README.md

# CI/CD Scripts for DanceLessonsCoach

## 🚀 Quick Start for Contributors

### You Only Need These Commands

```bash
# 1. Run tests (this is what matters most!)
go test ./...

# 2. Build binaries
./scripts/build.sh

# 3. Check formatting
go fmt ./...

# That's it! The CI/CD pipeline will handle the rest when you create a PR.
```

## 📖 Understanding the CI/CD Pipeline

### What Happens Automatically

When you push code or create a PR, GitHub Actions runs:

1. **Go CI/CD Pipeline** (`.gitea/workflows/go-ci-cd.yaml`)
   - Builds all Go packages
   - Runs tests with coverage
   - Checks code formatting
   - Validates workflow structure

2. **Docker Image Pipeline** (`.gitea/workflows/dockerimage.yaml`)
   - Builds Docker image (on main branch only)
   - Publishes to Gitea Container Registry
   - Tags with version and commit SHA

### When Does It Run?

| Event | Go CI/CD | Docker Image |
|-------|---------|--------------|
| Push to `main` | ✅ Yes | ✅ Yes |
| Push to `feature/*` | ✅ Yes | ❌ No |
| Push to `fix/*` | ✅ Yes | ❌ No |
| Push to `ci/*` | ✅ Yes | ❌ No |
| Pull Request | ✅ Yes | ❌ No |
| Manual trigger | ✅ Yes | ✅ Yes |

## 🧪 Local Testing Options

### Option 1: Simple Validation (No Docker Required)

```bash
# Just run the essentials
./scripts/cicd/contributor-quickstart.sh
```

This checks:
- ✅ Go installation
- ✅ All tests pass
- ✅ Code formatting
- ✅ Go vet analysis
- ✅ Workflow structure

### Option 2: Docker-Based Testing (Recommended)

```bash
# Test workflow compatibility with GitHub Actions
./scripts/cicd/test-act-local.sh
```

**Requirements:**
- Docker installed and running
- Internet connection (to pull images)

**What it does:**
- Validates YAML syntax
- Checks workflow structure
- Simulates GitHub Actions execution
- Tests both workflow files

### Option 3: Full CI/CD Simulation

```bash
# Complete local simulation
./scripts/cicd/test-cicd-simple.sh
```

**Requirements:**
- Docker installed and running
- More time (pulls multiple images)

**What it does:**
- YAML linting
- YAML validation
- Workflow structure validation
- Simulates build job
- Runs actual Go tests in containers

## 🐳 Docker Setup Guide

### For Windows Users

1. **Install Docker Desktop**
   - Download: https://www.docker.com/products/docker-desktop/
   - Enable WSL 2 backend (recommended)
   - Allocate at least 4GB RAM

2. **Verify Installation**
   ```powershell
   docker --version
   docker run hello-world
   ```

### For macOS Users

1. **Install Docker Desktop**
   - Download: https://www.docker.com/products/docker-desktop/
   - Grant necessary permissions

2. **Verify Installation**
   ```bash
   docker --version
   docker run hello-world
   ```

### For Linux Users

1. **Install Docker Engine**
   ```bash
   # Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install docker.io docker-compose
   sudo systemctl enable docker
   sudo systemctl start docker
   
   # Add user to docker group (avoid sudo)
   sudo usermod -aG docker $USER
   newgrp docker  # Reload group membership
   ```

2. **Verify Installation**
   ```bash
   docker --version
   docker run hello-world
   ```

## 🔧 Troubleshooting

### Docker Permission Issues

**Symptom:** `Got permission denied while trying to connect to the Docker daemon socket`

**Solution:**
```bash
# Linux/macOS
sudo usermod -aG docker $USER
newgrp docker

# Windows
Right-click Docker Desktop → Settings → Resources → WSL Integration → Enable
```

### Docker Not Running

**Symptom:** `Cannot connect to the Docker daemon`

**Solution:**
- Windows/macOS: Open Docker Desktop app
- Linux: `sudo systemctl start docker`

### Network Issues

**Symptom:** `Cannot pull Docker images`

**Solution:**
```bash
# Check internet connection
ping google.com

# Try pulling manually first
docker pull mikefarah/yq:latest
docker pull pipelinecomponents/yamllint:latest
```

### act Not Installed

**Symptom:** `act not found` in `test-act-local.sh`

**Solution:**
```bash
# Install act (optional - only needed for test-act-local.sh)
# macOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Windows (WSL)
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
```

## 📚 Script Reference

| Script | Purpose | Docker Required? | act Required? |
|--------|---------|------------------|---------------|
| `contributor-quickstart.sh` | Basic validation | ❌ No | ❌ No |
| `validate-workflow.sh` | Workflow structure | ❌ No | ❌ No |
| `test-act-local.sh` | GitHub Actions compatibility | ✅ Yes | ✅ Yes |
| `test-cicd-simple.sh` | Full CI/CD simulation | ✅ Yes | ❌ No |

## 🎯 Best Practices

### Before Submitting a PR

1. **Run tests locally**
   ```bash
   go test ./...
   ```

2. **Check formatting**
   ```bash
   go fmt ./...
   ```

3. **Build binaries**
   ```bash
   ./scripts/build.sh
   ```

4. **Validate workflows** (optional)
   ```bash
   ./scripts/cicd/validate-workflow.sh
   ```

### Working with the CI/CD Pipeline

- **Don't worry about Docker images** - The pipeline builds them automatically
- **Focus on tests** - If tests pass locally, they'll pass in CI/CD
- **Check PR status** - GitHub will show CI/CD results automatically
- **Fix failures** - If CI/CD fails, check the logs and fix issues

## 🔗 Useful Links

- **GitHub Actions Docs**: https://docs.github.com/en/actions
- **Docker Docs**: https://docs.docker.com/
- **act GitHub**: https://github.com/nektos/act
- **DanceLessonsCoach CI/CD**: See `.gitea/workflows/` directory

## 💡 Pro Tips

### Speed Up Local Testing

```bash
# Pull Docker images in advance
docker pull mikefarah/yq:latest
docker pull pipelinecomponents/yamllint:latest
docker pull node:16-buster-slim
```

### Test Specific Workflows

```bash
# Test Go CI/CD workflow only
act -W .gitea/workflows/go-ci-cd.yaml

# Test Docker workflow only
act -W .gitea/workflows/dockerimage.yaml
```

### Dry Run (No Execution)

```bash
# Check workflow syntax without running
echo 'm' | act -n -W .gitea/workflows/go-ci-cd.yaml
```

## 📞 Need Help?

If you're stuck with CI/CD setup:

1. **Check this documentation** - Most issues are covered here
2. **Run contributor-quickstart.sh** - It validates the essentials
3. **Ask in the PR** - We'll help you resolve any issues
4. **Check CI/CD logs** - GitHub shows detailed error messages

Remember: **You don't need to run CI/CD locally to contribute!** The pipeline runs automatically when you push code.