# Patch Creation Guide

This guide explains how to create patches for the IPTV Server system.

## Patch Structure

Each patch must follow this directory structure:
```
patches/vX.Y.Z-to-vA.B.C/
├── patch.json          # Patch metadata
├── files/              # Changed files
│   ├── modified/       # Files to be modified
│   ├── added/          # New files to add
│   └── deleted.json    # List of files to delete
├── scripts/            # Update scripts
│   ├── pre_update.sh   # Run before applying patch
│   ├── post_update.sh  # Run after applying patch
│   └── validate.sh     # Validation script
└── rollback/           # Rollback information
    └── rollback.json   # Rollback metadata
```

## patch.json Format

```json
{
  "version": "2.7.1",
  "from_version": "2.7.0",
  "release_date": "2025-01-20T00:00:00Z",
  "type": "bugfix|feature|security|critical",
  "requires_restart": true,
  "requires_migration": false,
  "auto_apply": false,
  "changelog": {
    "added": ["New feature descriptions"],
    "fixed": ["Bug fix descriptions"],
    "changed": ["Changed functionality"],
    "security": ["Security fixes"],
    "deprecated": ["Deprecated features"]
  },
  "files": {
    "modified": [
      {
        "path": "app/api/channels_api.py",
        "checksum": "sha256:...",
        "backup": true
      }
    ],
    "added": [
      {
        "path": "app/services/new_service.py",
        "checksum": "sha256:..."
      }
    ],
    "deleted": ["app/deprecated.py"]
  },
  "scripts": {
    "pre_update": "scripts/pre_update.sh",
    "post_update": "scripts/post_update.sh",
    "validate": "scripts/validate.sh"
  },
  "docker": {
    "rebuild": ["iptv-backend"],
    "restart": ["iptv-backend", "nginx"],
    "pull": []
  },
  "database": {
    "migrations": ["migrations/001_add_column.sql"],
    "backup_required": true
  },
  "validation": {
    "checksum": "sha256:...",
    "signature": "gpg:...",
    "min_version": "2.7.0",
    "max_version": "2.7.5"
  },
  "rollback": {
    "supported": true,
    "data_loss_risk": false,
    "instructions": "Automatic rollback available"
  }
}
```

## Creating a Patch

### 1. Identify Changes
```bash
# Compare versions
diff -r old_version/ new_version/ > changes.diff
```

### 2. Create Patch Directory
```bash
mkdir -p patches/v2.7.0-to-v2.7.1/{files,scripts,rollback}
mkdir -p patches/v2.7.0-to-v2.7.1/files/{modified,added}
```

### 3. Copy Modified Files
Place the NEW version of modified files in `files/modified/` maintaining the directory structure:
```
files/modified/
└── app/
    └── api/
        └── channels_api.py  # New version of the file
```

### 4. Add New Files
Place new files in `files/added/` with proper directory structure.

### 5. List Deleted Files
Create `files/deleted.json`:
```json
[
  "app/old_file.py",
  "frontend/deprecated.js"
]
```

### 6. Create Update Scripts

**pre_update.sh**:
```bash
#!/bin/bash
echo "Preparing to apply patch..."
# Stop services if needed
# Backup critical data
exit 0
```

**post_update.sh**:
```bash
#!/bin/bash
echo "Finalizing patch..."
# Restart services
# Run migrations
# Clear caches
exit 0
```

**validate.sh**:
```bash
#!/bin/bash
echo "Validating patch application..."
# Check file integrity
# Test critical functions
# Verify services are running
exit 0
```

### 7. Generate Checksums
```bash
# For each file
sha256sum file > file.sha256
```

### 8. Create Rollback Data
Store original files and database state in `rollback/` directory.

## Testing a Patch

1. **Test on Development System**
   ```bash
   ./patch-manager.py test patches/v2.7.0-to-v2.7.1
   ```

2. **Verify File Changes**
   - Check all files are properly modified
   - Verify checksums match

3. **Test Services**
   - Ensure all services start correctly
   - Test critical functionality

4. **Test Rollback**
   - Apply patch
   - Rollback
   - Verify system returns to previous state

## Publishing a Patch

1. **Commit to Git**
   ```bash
   git add patches/v2.7.0-to-v2.7.1
   git commit -m "Add patch v2.7.0 to v2.7.1"
   git push origin main
   ```

2. **Update current.json**
   ```json
   {
     "latest": "2.7.1",
     "stable": "2.7.1"
   }
   ```

3. **Create Release Manifest**
   Create `releases/v2.7.1.json` with version details.

4. **Tag Release**
   ```bash
   git tag -a v2.7.1 -m "Release v2.7.1"
   git push origin v2.7.1
   ```

## Patch Types

### Bugfix Patches
- Fix existing functionality
- No new features
- Minimal risk
- Can auto-apply

### Feature Patches
- Add new functionality
- May require configuration
- Medium risk
- Require confirmation

### Security Patches
- Fix vulnerabilities
- High priority
- Should auto-apply
- Include CVE references

### Critical Patches
- Fix critical system issues
- Highest priority
- May force update
- Include detailed instructions

## Best Practices

1. **Always Test First**
   - Never publish untested patches
   - Test on multiple configurations

2. **Maintain Compatibility**
   - Ensure backward compatibility
   - Document breaking changes

3. **Clear Documentation**
   - Detailed changelogs
   - Clear update instructions
   - Known issues

4. **Atomic Updates**
   - Each patch should be self-contained
   - Don't depend on other patches

5. **Rollback Safety**
   - Always provide rollback mechanism
   - Test rollback procedure
   - Document data loss risks

6. **Version Sequencing**
   - Patches must be applied in order
   - Can't skip versions
   - Validate version requirements