roi-theme/_planeacion/REORGANIZACION-TEMA.md

PROPUESTA: REORGANIZACIÓN Y LIMPIEZA DEL TEMA APUS

Fecha: 2025-11-04 Problema: Archivos .md innecesarios en el tema + mala organización de archivos en raíz

---

❌ PROBLEMA 1: ARCHIVOS .MD EN EL TEMA (MALA PRÁCTICA)

Archivos encontrados que NO deberían estar:

wp-content/themes/apus-theme/
├── CHANGELOG.md                        ❌ ELIMINAR
├── CREDITS.md                          ❌ ELIMINAR
├── ISSUE-14-COMPLETION-REPORT.md       ❌ ELIMINAR
├── ISSUE-19-COMPLETION-REPORT.md       ❌ ELIMINAR
├── ISSUES-6-7-COMPLETED.md             ❌ ELIMINAR
├── QUICK-START-OPTIONS-PANEL.md        ❌ ELIMINAR
├── README.md                           ❌ ELIMINAR
├── README-THEME-OPTIONS.md             ❌ ELIMINAR
├── SEO-COMPATIBILITY.md                ❌ ELIMINAR
├── TEMPLATES.md                        ❌ ELIMINAR
└── THEME-OPTIONS-STRUCTURE.txt         ❌ ELIMINAR

Total: 11 archivos de documentación que deben eliminarse

¿Por qué es mala práctica?

1. La documentación debe estar en GitHub Issues, no en archivos del tema
2. Aumenta el tamaño del tema innecesariamente
3. Dificulta el mantenimiento (documentación duplicada)
4. No es estándar de WordPress (temas profesionales no incluyen .md)

✅ Acción:

MOVER contenido a issues de GitHub y ELIMINAR archivos:

Archivo	Acción
CHANGELOG.md	Documentar en releases de GitHub
CREDITS.md	Agregar en style.css header
ISSUE-14-COMPLETION-REPORT.md	Ya está en issue #14 (cerrado) → ELIMINAR
ISSUE-19-COMPLETION-REPORT.md	Ya está en issue #19 (cerrado) → ELIMINAR
ISSUES-6-7-COMPLETED.md	Ya está en issues #6 y #7 → ELIMINAR
QUICK-START-OPTIONS-PANEL.md	Agregar en issue #14 (ya cerrado) → ELIMINAR
README.md	Crear README.md en RAÍZ del repo (no en tema)
README-THEME-OPTIONS.md	Fusionar con issue #14 → ELIMINAR
SEO-COMPATIBILITY.md	Fusionar con issue #19 → ELIMINAR
TEMPLATES.md	Fusionar con issue #9 → ELIMINAR
THEME-OPTIONS-STRUCTURE.txt	Fusionar con issue #14 → ELIMINAR

---

❌ PROBLEMA 2: DESORGANIZACIÓN EN LA RAÍZ DEL TEMA

Estructura ACTUAL (desordenada):

wp-content/themes/apus-theme/
├── 404.php                    ← Template
├── archive.php                ← Template
├── comments.php               ← Template
├── footer.php                 ← Template part
├── front-page.php             ← Template
├── functions.php              ✓ OK en raíz
├── header.php                 ← Template part
├── index.php                  ✓ OK en raíz (requerido)
├── page.php                   ← Template
├── search.php                 ← Template
├── sidebar.php                ← Template part
├── single.php                 ← Template
├── style.css                  ✓ OK en raíz (requerido)
├── LICENSE                    ✓ OK en raíz
├── .htaccess                  ❓ Verificar si es necesario
├── assets/                    ✓ OK
├── docs/                      ❓ ¿Qué contiene?
├── inc/                       ✓ OK
└── template-parts/            ✓ OK

✅ Estructura PROPUESTA (organizada):

wp-content/themes/apus-theme/
├── functions.php              ✓ REQUERIDO en raíz
├── style.css                  ✓ REQUERIDO en raíz
├── screenshot.png             ✓ REQUERIDO en raíz
├── index.php                  ✓ REQUERIDO en raíz (fallback)
├── LICENSE                    ✓ Opcional en raíz
│
├── templates/                 🆕 NUEVA CARPETA
│   ├── 404.php
│   ├── archive.php
│   ├── front-page.php
│   ├── page.php
│   ├── search.php
│   └── single.php
│
├── template-parts/            ✓ Ya existe
│   ├── header.php             ← MOVER aquí
│   ├── footer.php             ← MOVER aquí
│   ├── sidebar.php            ← MOVER aquí
│   ├── comments.php           ← MOVER aquí
│   ├── content.php
│   ├── content-none.php
│   ├── content-hero.php       🆕 Del template
│   ├── content-toc.php        🆕 Del template
│   ├── content-share.php      🆕 Del template
│   ├── content-cta.php        🆕 Del template
│   └── content-related.php    🆕 Del template
│
├── inc/                       ✓ Ya existe - bien organizado
│   ├── admin/
│   ├── adsense-delay.php
│   ├── category-badge.php
│   ├── critical-css.php
│   ├── customizer-fonts.php
│   ├── enqueue-scripts.php
│   ├── featured-image.php
│   ├── image-optimization.php
│   ├── performance.php
│   ├── related-posts.php
│   ├── sanitize-functions.php
│   ├── schema-markup.php      🆕 Del template
│   ├── seo.php
│   ├── template-functions.php
│   ├── template-tags.php
│   ├── theme-options-helpers.php
│   └── toc.php
│
└── assets/                    ✓ Ya existe - bien organizado
    ├── css/
    ├── js/
    ├── images/
    └── vendor/                🆕 Para Bootstrap local
        └── bootstrap/

---

🔄 PROBLEMA 3: NOMBRES DE ARCHIVOS INCONSISTENTES

❌ Problema: Inconsistencia en ubicación de template parts

Actual:

• header.php → Está en RAÍZ (debería estar en template-parts/)
• footer.php → Está en RAÍZ (debería estar en template-parts/)
• sidebar.php → Está en RAÍZ (debería estar en template-parts/)
• comments.php → Está en RAÍZ (debería estar en template-parts/)

WordPress permite template parts en raíz, pero es mala práctica por:

1. Desorganización visual
2. Dificulta encontrar archivos
3. No sigue estándares modernos de temas

✅ Solución:

MOVER a template-parts/ y actualizar referencias:

// ANTES:
get_header();
get_footer();
get_sidebar();

// DESPUÉS:
get_template_part('template-parts/header');
get_template_part('template-parts/footer');
get_template_part('template-parts/sidebar');

NOTA: get_header() y get_footer() buscan por defecto en raíz, pero podemos usar get_template_part() para mejor organización.

---

📋 PLAN DE ACCIÓN

Fase 1: Limpiar archivos .md

• Revisar contenido de cada .md
• Agregar información relevante a issues de GitHub correspondientes
• Eliminar los 11 archivos .md del tema
• Commit: "docs: eliminar archivos .md del tema (mover a GitHub issues)"

Fase 2: Reorganizar templates

• Crear carpeta templates/
• Mover 404.php, archive.php, front-page.php, page.php, search.php, single.php
• Actualizar functions.php si es necesario para que WordPress reconozca templates
• Commit: "refactor: reorganizar templates en carpeta templates/"

Fase 3: Reorganizar template parts

• Mover header.php a template-parts/header.php
• Mover footer.php a template-parts/footer.php
• Mover sidebar.php a template-parts/sidebar.php
• Mover comments.php a template-parts/comments.php
• Actualizar todas las referencias en templates que usen get_header(), get_footer(), etc.
• Commit: "refactor: mover template parts a carpeta template-parts/"

Fase 4: Crear estructura para nuevo template

• Crear template-parts/content-hero.php (vacío, para issue #11)
• Crear template-parts/content-toc.php (vacío, para issue #12)
• Crear template-parts/content-share.php (vacío, para nuevo issue)
• Crear template-parts/content-cta.php (vacío, para nuevo issue)
• Crear template-parts/content-related.php (vacío, para issue #13)
• Commit: "feat: agregar estructura de template parts para nuevo diseño"

Fase 5: Preparar assets para Bootstrap local

• Crear assets/vendor/bootstrap/
• Descargar Bootstrap 5.3.2
• Colocar en assets/vendor/bootstrap/css/ y assets/vendor/bootstrap/js/
• Actualizar inc/enqueue-scripts.php para cargar local (issue #5)
• Commit: "feat: agregar Bootstrap 5.3.2 local"

Fase 6: Testing

• Verificar que todos los templates siguen funcionando
• Verificar que header/footer/sidebar siguen cargando
• Verificar que no hay errores 404 en assets
• Commit: "test: verificar reorganización completa"

---

🎯 BENEFICIOS DE ESTA REORGANIZACIÓN

1. ✅ Cumple estándares de WordPress modernos
2. ✅ Más fácil de mantener (archivos agrupados por función)
3. ✅ Elimina redundancia (documentación solo en GitHub)
4. ✅ Reduce tamaño del tema (sin .md innecesarios)
5. ✅ Prepara estructura para implementar nuevo template
6. ✅ Facilita onboarding de nuevos desarrolladores

---

⚠️ CONSIDERACIONES

¿Afecta a WordPress?

NO - WordPress es flexible con la ubicación de archivos:

• Templates pueden estar en subcarpetas (con ajuste en functions.php)
• Template parts pueden estar en cualquier ubicación (usando get_template_part())

¿Rompe algo?

NO - Siempre que actualicemos las referencias correctamente:

• get_header() → get_template_part('template-parts/header')
• get_footer() → get_template_part('template-parts/footer')
• O configurar custom locations en functions.php

¿Es reversible?

SÍ - Todo está en Git, podemos revertir si hay problemas.

---

📌 ISSUE DE GITHUB SUGERIDO

Título: Reorganizar estructura de archivos del tema y eliminar documentación .md

Labels: enhancement, refactoring, cleanup, priority-medium

Milestone: Sprint 2025-12

Estimación: 2-3 horas

---

✅ CRITERIO DE DONE

• Todos los archivos .md eliminados del tema
• Contenido relevante de .md migrado a issues de GitHub
• Templates organizados en carpeta templates/
• Template parts organizados en carpeta template-parts/
• Bootstrap 5.3.2 descargado y en assets/vendor/bootstrap/
• Todas las referencias actualizadas
• Testing completo sin errores
• Commits con mensajes descriptivos
• Documentación en issue de GitHub actualizada