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

# 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_pep8.py - PEP8 compliance checking with safe auto-fix
• 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 ✅

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

# Validate all dependencies are available
python3 check-dependencies.py

Expected Result: All required dependencies reported as available

3. Core Functionality Test ✅

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

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

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

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

# 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

# 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

# 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

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