156 lines
4.2 KiB
Markdown
156 lines
4.2 KiB
Markdown
# 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`:
|
|
|
|
```text
|
|
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`):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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**:
|
|
|
|
```bash
|
|
git checkout main
|
|
git merge --squash pr-123
|
|
git commit --author="Nombre Apellido <email@ejemplo.com>"
|
|
```
|
|
|
|
|
|
### 4.3. Publicación en el repositorio oficial
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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.
|