IPTV-Updates/PATCH_CREATION_GUIDE.md

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

{
  "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

# Compare versions
diff -r old_version/ new_version/ > changes.diff

2. Create Patch Directory

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:

[
  "app/old_file.py",
  "frontend/deprecated.js"
]

6. Create Update Scripts

pre_update.sh:

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

post_update.sh:

#!/bin/bash
echo "Finalizing patch..."
# Restart services
# Run migrations
# Clear caches
exit 0

validate.sh:

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

7. Generate Checksums

# 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

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

   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

   {
     "latest": "2.7.1",
     "stable": "2.7.1"
   }
   

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

4. Tag Release

   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