Saltar al contenido principal

Sistema de Versionado y Actualizaciones

Sistema de Gestión de Reparaciones

Este documento explica cómo funciona el sistema de versionado automático y actualizaciones del plugin.

Índice​

  1. Versionado Semántico
  2. Actualizar Versión
  3. Sistema de Actualizaciones
  4. Publicar Nueva Versión
  5. Configurar GitHub
  6. Troubleshooting

Versionado Semántico​

El plugin usa Versionado Semántico (SemVer): MAJOR.MINOR.PATCH

Formato: X.Y.Z​

  • X (MAJOR): Cambios incompatibles con versiones anteriores
  • Y (MINOR): Nueva funcionalidad compatible con versiones anteriores
  • Z (PATCH): Correcciones de bugs compatibles

Ejemplos​

1.0.0 → 1.0.1  (PATCH)  - Corregido error de PHP 8.1
1.0.1 → 1.1.0  (MINOR)  - Añadido sistema de backup
1.1.0 → 2.0.0  (MAJOR)  - Rediseño completo de la BD (breaking change)

Actualizar Versión​

Usando el Script Automático​

El plugin incluye un script Python que actualiza automáticamente todos los archivos:

# Incrementar PATCH (1.0.0 → 1.0.1)
python3 actualizar-version.py patch

# Incrementar MINOR (1.0.0 → 1.1.0)
python3 actualizar-version.py minor

# Incrementar MAJOR (1.0.0 → 2.0.0)
python3 actualizar-version.py major

# Establecer versión específica
python3 actualizar-version.py 1.5.2

¿Qué Actualiza el Script?​

El script modifica automáticamente:

  1. ✅ sistema-reparaciones.php - Version header y define('SR_VERSION')
  2. ✅ README.md - Versión en el título
  3. ✅ CHANGELOG.md - Crea nueva entrada con fecha
  4. ✅ version.txt - Archivo de referencia

Flujo de Trabajo Recomendado​

# 1. Hacer cambios en el código
vim includes/admin/pages/dashboard.php

# 2. Actualizar versión según el tipo de cambio
python3 actualizar-version.py patch

# 3. Editar CHANGELOG.md y añadir los cambios específicos
vim CHANGELOG.md

# 4. Generar nuevo ZIP
python3 crear-zip-instalacion.py

# 5. Commit y tag en Git
git add .
git commit -m "Release v1.0.2: Corregido bug en dashboard"
git tag v1.0.2
git push origin main --tags

# 6. Crear GitHub Release con el ZIP
# (ver sección "Publicar Nueva Versión")

Sistema de Actualizaciones​

Cómo Funciona​

El plugin incluye includes/class-updater.php que:

  1. Verifica actualizaciones cada 12 horas desde GitHub Releases
  2. Muestra notificación en WordPress Admin cuando hay nueva versión
  3. Permite actualizar con un clic desde Plugins → Actualizar
  4. No requiere WordPress.org (usa GitHub directamente)

Arquitectura​

WordPress Admin
    ↓
class-updater.php
    ↓
GitHub API (https://api.github.com/repos/usuario/repo/releases/latest)
    ↓
Descarga ZIP → Instala → Activa

Verificación Manual​

Para forzar una verificación de actualizaciones:

WordPress Admin → Plugins → Sistema de Reparaciones
→ "Ver detalles de la versión"

O limpiar caché:

/wp-admin/plugins.php?sr_clear_update_cache=1

Publicar Nueva Versión​

Paso a Paso​

1. Preparar el Código​

# Actualizar versión
python3 actualizar-version.py patch

# Editar CHANGELOG con los cambios
vim CHANGELOG.md

2. Generar ZIP​

python3 crear-zip-instalacion.py

# Se crea: sistema-reparaciones-v1.0.X.zip

3. Commit y Tag en Git​

git add .
git commit -m "Release v1.0.X: Descripción de cambios"
git tag v1.0.X
git push origin main
git push origin --tags

4. Crear GitHub Release​

Opción A: Por Interfaz Web

  1. Ve a tu repositorio en GitHub
  2. Clic en "Releases" → "Create a new release"
  3. Selecciona el tag: v1.0.X
  4. Título: v1.0.X - Descripción corta
  5. Descripción: Copia el contenido de CHANGELOG para esta versión
  6. Arrastra el ZIP: sistema-reparaciones-v1.0.X.zip
  7. Clic en "Publish release"

Opción B: Por CLI (GitHub CLI)

# Instalar gh CLI: https://cli.github.com/

gh release create v1.0.X \
  sistema-reparaciones-v1.0.X.zip \
  --title "v1.0.X - Descripción" \
  --notes-file release-notes.md

5. Verificar​

  • Los usuarios verán la actualización en WordPress Admin
  • Pueden actualizar con un clic

Configurar GitHub​

1. Crear Repositorio​

# Inicializar Git (si no lo has hecho)
cd "SISTEMA DE REPARACIONES"
git init
git add .
git commit -m "Initial commit - v1.0.0"

# Crear repositorio en GitHub
# Ve a github.com → New Repository → "sistema-reparaciones"

# Conectar repositorio local
git remote add origin https://github.com/TU-USUARIO/sistema-reparaciones.git
git branch -M main
git push -u origin main

2. Configurar URL en el Plugin​

Edita includes/class-updater.php, línea ~40:

// ANTES (placeholder)
$this->update_url = 'https://api.github.com/repos/TU-USUARIO/sistema-reparaciones/releases/latest';

// DESPUÉS (tu repo real)
$this->update_url = 'https://api.github.com/repos/jose/sistema-reparaciones/releases/latest';

3. Hacer el Repositorio Público​

  • Ve a Settings → Danger Zone → Change visibility → Public
  • O déjalo privado y usa un Personal Access Token (ver abajo)

4. (Opcional) Repositorio Privado​

Si tu repo es privado, necesitas un token:

// En includes/class-updater.php, método get_remote_version()

$response = wp_remote_get(
    $this->update_url,
    array(
        'timeout' => 10,
        'headers' => array(
            'Accept' => 'application/json',
            'Authorization' => 'token TU_GITHUB_TOKEN', // Añadir esta línea
        ),
    )
);

Crear token: GitHub → Settings → Developer settings → Personal access tokens → Generate new token (scopes: repo)

Casos de Uso​

Caso 1: Corregir un Bug​

# 1. Corregir el bug
vim includes/admin/pages/dashboard.php

# 2. Actualizar a patch (1.0.1 → 1.0.2)
python3 actualizar-version.py patch

# 3. Actualizar CHANGELOG
vim CHANGELOG.md
# Añadir: "### Corregido: Error en cálculo de ingresos"

# 4. Generar ZIP y publicar
python3 crear-zip-instalacion.py
git add .
git commit -m "Fix: Corregido cálculo de ingresos en dashboard"
git tag v1.0.2
git push origin main --tags

# 5. Crear release en GitHub con el ZIP

Caso 2: Añadir Nueva Funcionalidad​

# 1. Desarrollar la funcionalidad
vim includes/admin/pages/statistics.php

# 2. Actualizar a minor (1.0.2 → 1.1.0)
python3 actualizar-version.py minor

# 3. Actualizar CHANGELOG
vim CHANGELOG.md
# Añadir: "### Añadido: Página de estadísticas avanzadas"

# 4. Publicar
python3 crear-zip-instalacion.py
git add .
git commit -m "Feature: Añadida página de estadísticas avanzadas"
git tag v1.1.0
git push origin main --tags

Caso 3: Breaking Change​

# 1. Hacer cambios incompatibles
vim includes/database/class-database.php

# 2. Actualizar a major (1.1.0 → 2.0.0)
python3 actualizar-version.py major

# 3. Documentar en CHANGELOG
vim CHANGELOG.md
# Añadir: "### BREAKING CHANGE: Nueva estructura de BD"

# 4. Publicar con advertencias
python3 crear-zip-instalacion.py
# En GitHub Release, marcar como "Pre-release" y advertir

Troubleshooting​

Problema: WordPress no detecta actualizaciones​

Causa: Caché de WordPress o GitHub API

Solución:

# Limpiar caché manualmente
/wp-admin/plugins.php?sr_clear_update_cache=1

# O desde código
delete_transient('sr_update_cache');

Problema: Error 404 al descargar actualización​

Causa: URL incorrecta o repositorio privado sin token

Solución:

  1. Verifica que el release existe en GitHub
  2. Verifica que el ZIP está adjunto al release
  3. Si es repo privado, añade token de GitHub

Problema: Actualización descarga pero no instala​

Causa: Estructura del ZIP incorrecta

Solución: Verifica que el ZIP tiene esta estructura:

sistema-reparaciones/
├── sistema-reparaciones.php
├── includes/
├── assets/
└── ...

NO debe ser:

sistema-reparaciones-main/  ← Incorrecto (GitHub por defecto)
└── sistema-reparaciones/

Usa crear-zip-instalacion.py para asegurar estructura correcta.

Problema: Script actualizar-version.py no encuentra archivos​

Causa: Ejecutado desde directorio incorrecto

Solución:

# Ejecutar siempre desde la raíz del plugin
cd "SISTEMA DE REPARACIONES"
python3 actualizar-version.py patch

Archivos del Sistema​

SISTEMA DE REPARACIONES/
├── actualizar-version.py          # Script de versionado
├── crear-zip-instalacion.py       # Script para generar ZIP
├── version.txt                     # Versión actual (auto-generado)
├── sistema-reparaciones.php       # Versión en header
├── CHANGELOG.md                    # Historial de cambios
├── includes/
│   └── class-updater.php          # Sistema de actualizaciones
└── docs/desarrollo/
    └── VERSIONADO_Y_ACTUALIZACIONES.md  # Este archivo

Checklist de Release​

Antes de publicar una nueva versión:

  • Código testeado y funcionando
  • Versión actualizada con actualizar-version.py
  • CHANGELOG.md actualizado con cambios específicos
  • ZIP generado con crear-zip-instalacion.py
  • Commit y tag creados en Git
  • GitHub Release creado con:
    • Tag correcto (v1.0.X)
    • Título descriptivo
    • Notas de la versión
    • ZIP adjunto
  • URL de actualizaciones configurada en class-updater.php
  • Actualización verificada en WordPress de prueba

Mejores Prácticas​

1. Versionado​

  • PATCH: Solo bugs, sin nuevas features
  • MINOR: Nuevas features compatibles
  • MAJOR: Cambios incompatibles (breaking changes)

2. CHANGELOG​

  • Ser específico: "Corregido error en dashboard" ✅
  • Evitar vaguedades: "Mejoras varias" ❌
  • Usar categorías: Añadido, Cambiado, Corregido, Eliminado

3. Testing​

  • Testear en WordPress limpio antes de release
  • Verificar actualización desde versión anterior
  • Testear en PHP 7.4, 8.0, 8.1, 8.2

4. Comunicación​

  • Releases grandes: avisar con anticipación
  • Breaking changes: documentar path de migración
  • Deprecations: advertir al menos una versión antes

Soporte​

¿Dudas sobre el sistema de versionado?

  • Lee este documento completo
  • Revisa ejemplos en la sección "Casos de Uso"
  • Verifica archivos existentes: CHANGELOG.md, version.txt

Sistema: Versionado Semántico + GitHub Releases Actualizado: 2026-02-10 Versión del Plugin: 1.0.1+