fenrir/RELEASE_CHECKLIST.md

# Fenrir Release Validation Checklist

This checklist ensures thorough validation before releasing Fenrir packages.

## 🔧 Setup Tools (One-time setup)

### Install Pre-commit Hook
```bash
# Safely install composite hook (preserves existing version management)
./tools/install_validation_hook.sh

# Test the hook
./.git/hooks/pre-commit
```

### Validation Scripts
- `tools/validate_syntax.py` - Python syntax validation
- `tools/validate_release.py` - Comprehensive release validation  
- `tools/cleanup_cache.py` - Remove Python cache files and directories
- `tools/pre-commit-hook` - Git pre-commit validation

## 📋 Pre-Release Checklist

### 1. Code Quality Validation ✅
```bash
# Comprehensive release validation (includes syntax, imports, structure)
python3 tools/validate_release.py

# If issues found, try auto-fix
python3 tools/validate_release.py --fix

# Quick validation (skips slow dependency checks)
python3 tools/validate_release.py --quick
```

**Expected Result**: All tests pass, no syntax errors

### 2. Dependency Validation ✅
```bash
# Validate all dependencies are available
python3 check-dependencies.py
```

**Expected Result**: All required dependencies reported as available

### 3. Core Functionality Test ✅
```bash
# Test core imports (safe to run without sudo)
cd src
python3 -c "
import fenrirscreenreader.core.fenrirManager
import fenrirscreenreader.core.commandManager
import fenrirscreenreader.core.eventManager
print('Core imports successful')
"
cd ..
```

**Expected Result**: No import errors

### 4. Installation Script Validation ✅
```bash
# Validate setup.py syntax
python3 -m py_compile setup.py

# Check setup.py can be parsed
python3 setup.py --help-commands >/dev/null
```

**Expected Result**: No syntax errors, setup.py functional

### 5. Configuration Validation ✅
```bash
# Verify config files exist and are parseable
ls -la config/settings/settings.conf
ls -la config/keyboard/desktop.conf
ls -la config/punctuation/default.conf
```

**Expected Result**: All core config files present

### 6. Manual Testing (User/Package Maintainer) ⚠️

**Important**: These require user interaction as they need sudo access or specific hardware.

```bash
# Test basic functionality (ask user to run)
sudo ./src/fenrir --help

# Test in emulation mode (safer for desktop environments)  
sudo ./src/fenrir -e --version

# Quick functionality test (3-5 seconds)
sudo timeout 5 ./src/fenrir -e -f || echo "Timeout reached (expected)"
```

**Expected Result**: No immediate crashes, basic help/version output works

### 7. Package-Specific Validation ✅
```bash
# Test the same compilation process used by package managers
python3 -m compileall src/fenrirscreenreader/ -q

# Verify no __pycache__ permission issues
find src/ -name "*.pyc" -delete
find src/ -name "__pycache__" -delete
```

**Expected Result**: Clean compilation, no permission errors

## 🚨 Known Issue Categories

### Critical Issues (Block Release)
- **Python syntax errors** (SyntaxError, unterminated strings)
- **Missing core dependencies** (dbus-python, evdev, etc.)
- **Import failures in core modules** (fenrirManager, commandManager)
- **Missing critical config files** (settings.conf, desktop.conf)

### Warning Issues (Address if Possible)
- **PEP8 violations** (cosmetic, don't block release)
- **Missing optional dependencies** (for specific features)
- **Command structure issues** (missing methods in command files)
- **Very long lines** (>120 characters)

## 🔍 Root Cause Analysis

### Why These Errors Weren't Caught Previously

1. **No automated syntax validation** - The codebase relied on manual testing
2. **No pre-commit hooks** - Syntax errors could be committed
3. **No CI/CD pipeline** - Package compilation happens only during release
4. **Manual PEP8 cleanup** - F-string refactoring introduced syntax errors during batch cleanup

## 📖 Usage Instructions

### For Developers
```bash
# Before committing changes
git add .
git commit  # Pre-commit hook will run automatically

# Before creating tags/releases
python3 tools/validate_release.py
```

### For Package Maintainers
```bash
# Before packaging
python3 tools/validate_release.py

# If validation fails
python3 tools/validate_release.py --fix

# Quick check (if dependencies are known good)
python3 tools/validate_release.py --quick
```

### For Release Managers
```bash
# Complete validation before tagging
python3 tools/validate_release.py

# Manual verification (requires sudo)
sudo ./src/fenrir --version

# Tag release only after all validations pass
git tag -a v2.x.x -m "Release v2.x.x"
```

## 🎯 Future Improvements

### Recommended Additions
1. **GitHub Actions CI/CD** - Automated validation on every push
2. **Automated testing** - Unit tests for core functionality  
3. **Integration testing** - Test driver interactions
4. **Package testing** - Validate actual package installation

### Modern Python Packaging
- Consider migrating to `pyproject.toml` (PEP 621)
- Use `build` instead of `setup.py` directly
- Add `tox.ini` for multi-environment testing

## 📞 Support

If validation fails and auto-fix doesn't resolve issues:

1. **Check the specific error messages** in validation output
2. **Review recent commits** that might have introduced issues
3. **Run individual validation steps** to isolate problems

Remember: **Working code is better than perfect code** - especially for accessibility software where reliability is critical.