From dd5cdb19cf4250a37ba47530937f4c2e09050c63 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Sun, 21 Dec 2025 09:47:35 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Actualiza=20las=20gu=C3=ADas=20d?= =?UTF-8?q?e=20contribuci=C3=B3n?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 121 +++++++++------------------ MAINTAINERS.md | 211 ++++++++++++++++++------------------------------ 2 files changed, 113 insertions(+), 219 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2e2a263..e0e275a4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. + ` (ámbito opcional): ` -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. diff --git a/MAINTAINERS.md b/MAINTAINERS.md index fbf69db3..25559841 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -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//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 -``` - - -## 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 " ``` -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 -``` - - -## 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` (``). +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.