manuelcillero/pagetop
manuelcillero/pagetop
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

📝 Actualiza las guías de contribución

Browse source
This commit is contained in:
Manuel Cillero 2025-12-21 09:47:35 +01:00
parent 1bf3800ea6
commit f7023469e2
2 changed files with 113 additions and 219 deletions
Download patch file Download diff file Expand all files Collapse all files

121
CONTRIBUTING.md
View file

@ -15,19 +15,10 @@ PageTop mantiene **un único repositorio oficial**:
* **Repositorio oficial:** https://git.cillero.es/manuelcillero/pagetop
* **Repositorio espejo:** https://github.com/manuelcillero/pagetop
El repositorio de GitHub actúa como espejo y punto de entrada para:
* dar mayor visibilidad al proyecto,
* facilitar la participación de la comunidad,
* centralizar *issues* y *pull requests* externas.
> ⚠️ **Importante**
> Aunque GitHub permite abrir *pull requests*, **la integración del código se realiza únicamente en
> el repositorio oficial**. El repositorio de GitHub se sincroniza posteriormente para reflejar el
> mismo estado.
En todos los casos, se respeta la **autoría original** de las contribuciones integradas, tanto en el
historial como en la documentación asociada al cambio.
> Aunque GitHub permite abrir *issues* y *pull requests*, **la integración del código se realiza
> únicamente en el repositorio oficial**. GitHub actúa como repositorio espejo que se sincroniza
> automáticamente para reflejar el mismo estado.
## 2. Issues (incidencias, propuestas, preguntas)
@ -50,8 +41,8 @@ Las *issues* se usan para:
### 3.1 Dónde abrirlas
Las *pull requests* se abren **en GitHub**, contra la rama `main`. GitHub es el punto de entrada
recomendado para contribuciones externas.
Las *pull requests* se abren **en GitHub**, normalmente contra la rama `main`. GitHub es el punto de
entrada recomendado para contribuciones externas.
### 3.2 Reglas generales para PRs
@ -63,68 +54,22 @@ recomendado para contribuciones externas.
### 3.3 Revisión y aceptación
Todas las PRs:
Todas las PRs son **revisadas manualmente** y pueden recibir comentarios o solicitudes de cambios.
* serán **revisadas manualmente**,
* pueden recibir comentarios o solicitudes de cambios,
* **no se integran directamente en GitHub**, ya que la integración se realiza en el repositorio
oficial para mantener coherencia y trazabilidad.
Una PR aceptada:
* se integra en el repositorio oficial (Forgejo),
* respetando **la autoría original del contribuidor**,
* normalmente mediante **squash merge** para mantener un historial limpio.
Las PRs aceptadas se integran en el repositorio oficial, nunca directamente en GitHub, preservando
siempre la **autoría original** del contribuidor.
## 4. Autoría y atribución
### 3.4. Cierre de Pull Requests y sincronización
PageTop cuida especialmente la atribución de contribuciones.
Una vez que el cambio ha sido integrado en el repositorio oficial:
* El **autor original del código se conserva** en el commit final integrado en Forgejo.
* Aunque el autor no tenga cuenta en Forgejo, su nombre y email quedarán reflejados.
* En GitHub, cuando es posible, la contribución quedará asociada al usuario original.
Adicionalmente, el mensaje del commit puede incluir líneas `Co-authored-by` cuando proceda.
* La PR en GitHub se **cierra manualmente**.
* Se añade un **mensaje estándar de cierre** indicando que el cambio ha sido integrado.
* El repositorio de GitHub **se sincroniza automáticamente** como espejo.
## 5. Cierre de Pull Requests en GitHub
Una vez que el cambio ha sido integrado en Forgejo:
* La PR en GitHub se **cerrará manualmente** (no se mergea).
* Se añadirá un **mensaje estándar de cierre**, indicando:
* que el cambio ha sido integrado,
* la referencia al commit o versión,
* que GitHub es un repositorio espejo.
Ejemplo de mensaje de cierre:
> Este cambio ha sido integrado en el repositorio oficial (Forgejo).
> GitHub actúa como repositorio espejo, por lo que la PR se cierra sin merge.
> Gracias por tu contribución.
Esto garantiza:
* transparencia,
* trazabilidad,
* coherencia entre repositorios.
## 6. Sincronización entre Forgejo y GitHub
Tras integrar cambios en Forgejo:
* el repositorio de GitHub se **actualiza para reflejar el estado de Forgejo**,
* el historial de GitHub puede reescribirse para mantener coherencia.
Por este motivo:
* **no se deben hacer merges “definitivos” en GitHub**,
* GitHub no debe considerarse fuente de verdad del historial.
## 7. Estilo de código y calidad
## 4. Estilo de código y calidad
* Sigue el estilo existente del proyecto.
* Mantén los comentarios claros y precisos.
@ -132,18 +77,28 @@ Por este motivo:
* Cambios públicos o estructurales deben ir acompañados de documentación.
## 8. Commits
## 5. Commits
Recomendaciones generales:
PageTop usa la especificación **gitmoji** para los mensajes de *commit*. El formato recomendado es:
* Mensajes claros y descriptivos.
* Un commit debe representar una unidad lógica de cambio.
* En contribuciones externas, el formato exacto del commit puede ajustarse durante la integración.
`<propósito> (ámbito opcional): <mensaje>`
Durante la integración, los commits pueden ajustarse (rebase, squash o edición de mensajes) para
adaptarse al historial del proyecto.
Ejemplos:
## 9. Comunicación y respeto
* 📝 Actualiza la guía de contribución
* ✨ (locale): Refactoriza sistema de localización
* ♻️ (bootsier): Simplifica asignación de clases
El emoji puede usarse en formato Unicode o como *shortcode*, por ejemplo `:sparkles:` en vez de ✨.
Consulta la especificación oficial en https://gitmoji.dev/specification
Durante la integración, los *commits* pueden ajustarse para adaptarse al historial del proyecto.
Un *commit* debe representar una unidad lógica de cambio. Usa mensajes claros y descriptivos.
## 6. Comunicación y respeto
PageTop sigue un enfoque profesional y colaborativo:
@ -151,13 +106,9 @@ PageTop sigue un enfoque profesional y colaborativo:
* Acepta sugerencias técnicas como parte del proceso.
* Recuerda que todas las contribuciones son revisadas con el objetivo de mejorar el proyecto.
Si tienes dudas sobre el proceso, abre una *issue* de tipo pregunta para tratar la cuestión en
comunidad.
## 10. Dudas
---
Si tienes dudas sobre el proceso:
* abre una *issue* de tipo pregunta,
* o inicia una discusión (si está habilitada).
Gracias por contribuir a **PageTop** 🚀 Cada aportación, grande o pequeña, ayuda a que el proyecto
mejore.
Gracias por contribuir a **PageTop** 🚀 Cada aportación contribuye a mejorar el proyecto.

211
MAINTAINERS.md
View file

@ -10,204 +10,147 @@ usuarios externos**. Su objetivo es servir como **referencia operativa**, garant
trazabilidad y preservación de la autoría en un entorno con repositorios espejo.
## 1. Repositorios y roles
## 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
El repositorio de GitHub actúa como espejo y punto de entrada para:
* dar mayor visibilidad al proyecto,
* facilitar la participación de la comunidad,
* centralizar *issues* y *pull requests* externas.
### 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
Configuración típica de *remotes*:
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.
```bash
git remote -v
```
Ejemplo esperado:
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 git@github.com:manuelcillero/pagetop.git (push)
github git@github.com:manuelcillero/pagetop.git (fetch)
github DISABLED (push)
```
Convenciones usadas en este documento:
* `origin` -> Oficial
* `github` -> GitHub (espejo)
* `origin` -> Repositorio oficial
* `github` -> Repositorio espejo
## 3. Recepción de Pull Requests desde GitHub
## 3. Recepción y revisión de Pull Requests
Las contribuciones externas llegan como *pull requests* en GitHub, normalmente contra `main`.
Las PRs externas llegan por GitHub, normalmente contra la rama `main`.
### 3.1 Obtener la PR en local
Opción habitual (ejemplo con PR #123):
Se asume que el repositorio local está configurado para recuperar PRs de GitHub como referencias
remotas (`refs/pull/<N>/head`):
```bash
git fetch github pull/123/head:pr-123
git checkout pr-123
git fetch github --prune
git checkout -b pr-123 github/pr/123
```
Alternativamente, si la rama del contribuidor es accesible directamente como referencia remota:
Antes de integrar:
```bash
git fetch github
git checkout nombre-de-la-rama
```
* 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. Revisión local
## 4. Estrategia de integración
Antes de integrar cualquier cambio:
La integración **se realiza siempre en el repositorio oficial** (`origin`).
* Revisar el código manualmente.
* Verificar compilación y pruebas:
### 4.1 Estrategia por defecto: *rebase* + *fast-forward*
```bash
cargo build
cargo test
```
Esta es la **estrategia estándar y recomendada** en PageTop. Ventajas:
* Comprobar impacto en documentación.
* Evaluar coherencia con la arquitectura y el estilo del proyecto.
Si se requieren cambios:
* comentar en la PR,
* solicitar ajustes,
* o realizar modificaciones locales explicadas claramente.
## 5. Estrategia de integración
La integración **se realiza siempre en el repositorio oficial**.
### 5.1 Estrategia por defecto: *squash merge*
Usada cuando:
* la PR tiene varios commits intermedios,
* los commits no siguen el estilo del proyecto,
* se desea un historial compacto.
* 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 pull origin main
git merge --squash pr-123
```
Crear el commit final **preservando la autoría** (ver sección 6).
### 5.2 Cherry-pick selectivo
Usado cuando:
* uno o varios commits son claros y autocontenidos,
* interesa conservar referencias explícitas.
Ejemplo:
```bash
git checkout main
git pull origin main
git cherry-pick -x <commit-sha>
```
## 6. Preservación de la autoría
La autoría original **debe conservarse siempre**.
### 6.1 Commit con autor explícito
Ejemplo:
```bash
git commit --author="Nombre Apellido <email@ejemplo.com>"
```
El mantenedor figura como *committer*; el contribuidor como *author*.
### 6.2 Co-authored-by
Cuando procede, puede añadirse al mensaje del commit:
```text
Co-authored-by: Nombre Apellido <email@ejemplo.com>
```
## 7. Push al repositorio oficial
Una vez integrado:
### 4.3. Publicación en el repositorio oficial
```bash
git push origin main
```
Este push representa **la integración definitiva**.
Este *push* representa la **integración definitiva** del cambio en la rama `main`.
## 8. Cierre de la Pull Request en GitHub
## 5. Cierre de la PR y sincronización
Tras integrar el cambio en el repositorio oficial:
* **No se mergea la PR en GitHub**.
* Se cierra manualmente con un mensaje estándar.
Ejemplo recomendado:
Tras integrar el cambio en el repositorio oficial, se cierra manualmente la PR en GitHub con un
mensaje estándar:
```text
Este cambio ha sido integrado en el repositorio oficial.
GitHub actúa como repositorio espejo, por lo que la PR se cierra sin merge.
Gracias por tu contribución.
Este cambio ha sido integrado en el repositorio oficial en `main` (`<hash>`).
GitHub actúa como repositorio espejo sincronizado.
```
## 9. Sincronización del repositorio oficial a GitHub
## 6. Principios de mantenimiento
El repositorio de GitHub se mantiene como **espejo automático** del repositorio oficial
mediante un **push mirror configurado**.
No se realizan sincronizaciones manuales desde clones locales.
### Consideraciones
* El repositorio oficial es siempre la **fuente de verdad**.
* El historial de GitHub puede **reescribirse automáticamente** para reflejar el estado del
repositorio oficial.
* Todas las ramas que deban preservarse en GitHub **deben existir también en el repositorio
oficial**.
* GitHub no debe usarse como referencia del historial real.
## 10. 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.
* 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.
Su objetivo no es imponer rigidez, sino **capturar el conocimiento operativo real** de PageTop.
No se trata de imponer rigidez, sino de **capturar el conocimiento operativo real** de PageTop como
guía práctica para el mantenimiento.