pagetop/MAINTAINERS.md

MAINTAINERS.md

Guía para mantenedores de PageTop

Este documento describe el flujo técnico interno de revisión e integración de contribuciones en PageTop.

Está dirigido a mantenedores del proyecto y no forma parte de la guía de contribución para usuarios externos. Su objetivo es servir como referencia operativa, garantizando coherencia, trazabilidad y preservación de la autoría en un entorno con repositorios espejo.

1. Repositorios y principios

PageTop mantiene un único repositorio oficial:

• Repositorio oficial: https://git.cillero.es/manuelcillero/pagetop
• Repositorio espejo: https://github.com/manuelcillero/pagetop

Principios clave

• El repositorio oficial es la única fuente de verdad del historial.
• Nunca se realizan merges en GitHub.
• Toda integración definitiva se realiza en el repositorio oficial.
• La autoría original debe preservarse siempre.

2. Configuración local recomendada

El remoto github debe configurarse únicamente para operaciones de lectura (fetch), con la URL de push deshabilitada para evitar publicaciones accidentales en el repositorio espejo.

Estado esperado de git remote -v:

origin   git@git.cillero.es:manuelcillero/pagetop.git (fetch)
origin   git@git.cillero.es:manuelcillero/pagetop.git (push)
github   git@github.com:manuelcillero/pagetop.git     (fetch)
github   DISABLED                                     (push)

Convenciones usadas en este documento:

• origin -> Repositorio oficial
• github -> Repositorio espejo

3. Recepción y revisión de Pull Requests

Las PRs externas llegan por GitHub, normalmente contra la rama main.

Se asume que el repositorio local está configurado para recuperar PRs de GitHub como referencias remotas (refs/pull/<N>/head):

git fetch github --prune
git checkout -b pr-123 github/pr/123

Antes de integrar:

• Revisar el código manualmente.

• Verificar formato, análisis y pruebas:

  cargo fmt
  cargo clippy
  cargo test
  

• Comprobar impacto en documentación.

• Evaluar coherencia con la arquitectura y el estilo del proyecto.

Los cambios adicionales se solicitan o se aplican explicando claramente el motivo.

4. Estrategia de integración

La integración se realiza siempre en el repositorio oficial (origin).

4.1 Estrategia por defecto: rebase + fast-forward

Esta es la estrategia estándar y recomendada en PageTop. Ventajas:

• conserva los commits originales,
• preserva la autoría real de cada cambio,
• mantiene un historial lineal y trazable,
• facilita auditoría y depuración.

Procedimiento típico:

git checkout pr-123
git rebase main

# Resolver conflictos si los hay

git checkout main
git merge --ff-only pr-123

Si merge --ff-only falla, no se debe continuar, indica divergencias que deben resolverse antes de integrar la PR.

4.2 Estrategia excepcional: Squash

Sólo debe usarse cuando esté justificado:

• la PR contiene múltiples commits de prueba o ruido,
• el historial aportado no es significativo,
• el cambio es pequeño y autocontenido.

En este caso, se debe preservar explícitamente la autoría:

git checkout main
git merge --squash pr-123
git commit --author="Nombre Apellido <email@ejemplo.com>"

4.3. Publicación en el repositorio oficial

git push origin main

Este push representa la integración definitiva del cambio en la rama main.

5. Cierre de la PR y sincronización

Tras integrar el cambio en el repositorio oficial, se cierra manualmente la PR en GitHub con un mensaje estándar:

Gracias por tu contribución.

Este cambio ha sido integrado en el repositorio oficial en `main` (`<hash>`).
GitHub actúa como repositorio espejo sincronizado.

6. Principios de mantenimiento

• Priorizar claridad y trazabilidad frente a rapidez.
• Mantener un historial legible y significativo.
• Documentar cambios estructurales o públicos.
• Tratar las contribuciones externas con respeto y transparencia.

---

Este documento puede evolucionar con el proyecto.

No se trata de imponer rigidez, sino de capturar el conocimiento operativo real de PageTop como guía práctica para el mantenimiento.