maybe finally done

2025-08-25 11:18:48 -05:00
parent 9499d1095e
commit d340a76422
6 changed files with 794 additions and 225 deletions
@@ -0,0 +1,149 @@
+# Release Workflow Documentation
+
+This document describes the automated release workflow for the Android File Handler ADB tool.
+
+## Overview
+
+The release workflow automatically builds and publishes native binaries for multiple platforms when a new tag is pushed. It creates:
+
+- **Linux Binary**: Native executable for Linux systems
+- **Windows Binary**: Native executable (.exe) for Windows systems  
+- **DEB Packages**: Debian/Ubuntu packages (.deb)
+- **RPM Packages**: Red Hat/Fedora packages (.rpm)
+- **AUR Package**: Arch User Repository submission
+
+## Triggering a Release
+
+1. **Create and push a tag**:
+   ```bash
+   git tag v1.0.0
+   git push origin v1.0.0
+   ```
+
+2. **Manual workflow dispatch** (optional):
+   - Go to Actions tab in GitHub
+   - Select "Release" workflow
+   - Click "Run workflow"
+   - Optionally enable "Dry Run" mode
+
+## Required Repository Secrets
+
+For AUR publishing, configure these secrets in repository settings:
+
+| Secret Name | Description |
+|-------------|-------------|
+| `AUR_SSH_PRIVATE_KEY` | SSH private key for AUR publishing |
+| `AUR_USER_NAME` | Git username for AUR commits |
+| `AUR_USER_EMAIL` | Git email for AUR commits |
+
+## Workflow Features
+
+### Multi-Platform Builds
+- **Linux**: Built on Ubuntu with PyInstaller
+- **Windows**: Cross-compiled on Ubuntu with PyInstaller
+- **Arch Linux**: Built in native Arch container
+
+### Security Features
+- SHA256 checksums for all release assets
+- Comprehensive file validation
+- Binary integrity verification
+
+### Package Management
+- **DEB**: Created with `fpm` for APT repositories
+- **RPM**: Created with `fpm` for DNF/YUM repositories
+- **AUR**: Automated PKGBUILD generation and submission
+
+### Quality Assurance
+- Binary size validation (must be > 1MB)
+- File existence verification
+- Build success validation
+- Comprehensive error reporting
+
+## Dry Run Mode
+
+Enable dry run mode to test the workflow without publishing:
+
+1. Go to Actions → Release workflow
+2. Click "Run workflow"
+3. Check "Enable dry run mode"
+4. Click "Run workflow"
+
+In dry run mode:
+- All builds are executed
+- Validation is performed
+- No actual publishing occurs
+- Assets are still created for review
+
+## Build Outputs
+
+### Release Assets
+All builds create files in the `release-assets/` directory:
+
+```
+release-assets/
+├── android-file-handler           # Linux binary
+├── android-file-handler.exe       # Windows binary  
+├── android-file-handler_*.deb     # Debian packages
+├── android-file-handler-*.rpm     # RPM packages
+└── SHA256SUMS                     # Checksums file
+```
+
+### Validation Reports
+The workflow provides comprehensive build quality assessment:
+
+- ✅/❌ Binary creation success
+- ✅/❌ Package count validation
+- 📊 File size verification
+- 🔒 SHA256 checksum generation
+
+## Troubleshooting
+
+### Common Issues
+
+1. **No release assets created**
+   - Check artifact download step
+   - Verify PyInstaller execution
+   - Review build logs for errors
+
+2. **Binary validation fails**
+   - Ensure binaries are > 1MB
+   - Check file permissions
+   - Verify executable format
+
+3. **AUR publishing fails**
+   - Verify SSH key configuration
+   - Check AUR credentials
+   - Ensure PKGBUILD syntax
+
+### Debug Steps
+
+1. **Enable dry run mode** to test without publishing
+2. **Check build logs** for specific error messages
+3. **Verify dependencies** in pyproject.toml
+4. **Test locally** with PyInstaller before pushing
+
+## Maintenance
+
+### Updating the Workflow
+
+When modifying the workflow:
+
+1. Test changes in a fork first
+2. Use dry run mode for validation
+3. Monitor build quality metrics
+4. Update this documentation
+
+### Version Requirements
+
+- Python 3.8+ (specified in workflow)
+- Poetry for dependency management
+- ADB platform tools (bundled)
+
+## Security Considerations
+
+- SSH keys are properly secured and permissioned
+- Checksums provide integrity verification
+- Secrets are never logged or exposed
+- Build artifacts are validated before release
+
+This workflow ensures reliable, secure, and comprehensive multi-platform releases for the Android File Handler ADB tool.