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 fea5564a62
commit fee6a23543
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 oficial:** https://git.cillero.es/manuelcillero/pagetop
* **Repositorio espejo:** https://github.com/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** > ⚠️ **Importante**
> Aunque GitHub permite abrir *pull requests*, **la integración del código se realiza únicamente en > Aunque GitHub permite abrir *issues* y *pull requests*, **la integración del código se realiza
> el repositorio oficial**. El repositorio de GitHub se sincroniza posteriormente para reflejar el > únicamente en el repositorio oficial**. GitHub actúa como repositorio espejo que se sincroniza
> mismo estado. > automáticamente 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.
## 2. Issues (incidencias, propuestas, preguntas) ## 2. Issues (incidencias, propuestas, preguntas)
@ -50,8 +41,8 @@ Las *issues* se usan para:
### 3.1 Dónde abrirlas ### 3.1 Dónde abrirlas
Las *pull requests* se abren **en GitHub**, contra la rama `main`. GitHub es el punto de entrada Las *pull requests* se abren **en GitHub**, normalmente contra la rama `main`. GitHub es el punto de
recomendado para contribuciones externas. entrada recomendado para contribuciones externas.
### 3.2 Reglas generales para PRs ### 3.2 Reglas generales para PRs
@ -63,68 +54,22 @@ recomendado para contribuciones externas.
### 3.3 Revisión y aceptación ### 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**, Las PRs aceptadas se integran en el repositorio oficial, nunca directamente en GitHub, preservando
* pueden recibir comentarios o solicitudes de cambios, siempre la **autoría original** del contribuidor.
* **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.
## 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. * La PR en GitHub se **cierra manualmente**.
* Aunque el autor no tenga cuenta en Forgejo, su nombre y email quedarán reflejados. * Se añade un **mensaje estándar de cierre** indicando que el cambio ha sido integrado.
* En GitHub, cuando es posible, la contribución quedará asociada al usuario original. * El repositorio de GitHub **se sincroniza automáticamente** como espejo.
Adicionalmente, el mensaje del commit puede incluir líneas `Co-authored-by` cuando proceda.
## 5. Cierre de Pull Requests en GitHub ## 4. Estilo de código y calidad
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
* Sigue el estilo existente del proyecto. * Sigue el estilo existente del proyecto.
* Mantén los comentarios claros y precisos. * 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. * 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. `<propósito> (ámbito opcional): <mensaje>`
* Un commit debe representar una unidad lógica de cambio.
* En contribuciones externas, el formato exacto del commit puede ajustarse durante la integración.
Durante la integración, los commits pueden ajustarse (rebase, squash o edición de mensajes) para Ejemplos:
adaptarse al historial del proyecto.
## 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: 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. * Acepta sugerencias técnicas como parte del proceso.
* Recuerda que todas las contribuciones son revisadas con el objetivo de mejorar el proyecto. * 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: Gracias por contribuir a **PageTop** 🚀 Cada aportación contribuye a mejorar el proyecto.
* 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.

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. 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**: PageTop mantiene **un único repositorio oficial**:
* **Repositorio oficial:** https://git.cillero.es/manuelcillero/pagetop * **Repositorio oficial:** https://git.cillero.es/manuelcillero/pagetop
* **Repositorio espejo:** https://github.com/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 ### Principios clave
* El repositorio oficial **es la única fuente de verdad** del historial. * El repositorio oficial **es la única fuente de verdad** del historial.
* **Nunca se realizan *merges* en GitHub**. * **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 ## 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 Estado esperado de `git remote -v`:
git remote -v
```
Ejemplo esperado:
```text ```text
origin git@git.cillero.es:manuelcillero/pagetop.git (fetch) origin git@git.cillero.es:manuelcillero/pagetop.git (fetch)
origin git@git.cillero.es:manuelcillero/pagetop.git (push) origin git@git.cillero.es:manuelcillero/pagetop.git (push)
github git@github.com:manuelcillero/pagetop.git (fetch) github git@github.com:manuelcillero/pagetop.git (fetch)
github git@github.com:manuelcillero/pagetop.git (push) github DISABLED (push)
``` ```
Convenciones usadas en este documento: Convenciones usadas en este documento:
* `origin` -> Oficial * `origin` -> Repositorio oficial
* `github` -> GitHub (espejo) * `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 Se asume que el repositorio local está configurado para recuperar PRs de GitHub como referencias
remotas (`refs/pull/<N>/head`):
Opción habitual (ejemplo con PR #123):
```bash ```bash
git fetch github pull/123/head:pr-123 git fetch github --prune
git checkout pr-123 git checkout -b pr-123 github/pr/123
``` ```
Alternativamente, si la rama del contribuidor es accesible directamente como referencia remota: Antes de integrar:
```bash * Revisar el código manualmente.
git fetch github * Verificar formato, análisis y pruebas:
git checkout nombre-de-la-rama
``` ```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. ### 4.1 Estrategia por defecto: *rebase* + *fast-forward*
* Verificar compilación y pruebas:
```bash Esta es la **estrategia estándar y recomendada** en PageTop. Ventajas:
cargo build
cargo test
```
* Comprobar impacto en documentación. * conserva los commits originales,
* Evaluar coherencia con la arquitectura y el estilo del proyecto. * preserva la autoría real de cada cambio,
* mantiene un historial lineal y trazable,
Si se requieren cambios: * facilita auditoría y depuración.
* 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.
Procedimiento típico: 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 ```bash
git checkout main git checkout main
git pull origin main
git merge --squash pr-123 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>" git commit --author="Nombre Apellido <email@ejemplo.com>"
``` ```
El mantenedor figura como *committer*; el contribuidor como *author*.
### 6.2 Co-authored-by ### 4.3. Publicación en el repositorio oficial
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:
```bash ```bash
git push origin main 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: Tras integrar el cambio en el repositorio oficial, se cierra manualmente la PR en GitHub con un
mensaje estándar:
* **No se mergea la PR en GitHub**.
* Se cierra manualmente con un mensaje estándar.
Ejemplo recomendado:
```text ```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. 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 * Priorizar **claridad y trazabilidad** frente a rapidez.
mediante un **push mirror configurado**. * Mantener un historial legible y significativo.
* Documentar cambios estructurales o públicos.
No se realizan sincronizaciones manuales desde clones locales. * Tratar las contribuciones externas con respeto y transparencia.
### 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.
--- ---
Este documento puede evolucionar con el proyecto. 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.