diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c2e2a263 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,163 @@ +# Guía de contribución a PageTop + +Gracias por tu interés en contribuir a **PageTop** 🎉 + +Este documento describe **cómo participar en el desarrollo del proyecto**, el flujo de trabajo y las +normas que permitan garantizar un historial limpio, trazable y sostenible a largo plazo. + +Por favor, léelo completo antes de abrir una *issue* o una *pull request*. + + +## 1. Repositorios + +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. + + +## 2. Issues (incidencias, propuestas, preguntas) + +Antes de abrir una *issue* **en GitHub**: + + * comprueba que no exista ya una similar, + * describe claramente el problema o propuesta, + * incluye pasos de reproducción si se trata de un *bug*, + * indica versión, entorno y contexto cuando sea relevante. + +Las *issues* se usan para: + + * informar de errores, + * propuestas de mejora, + * discusión técnica previa a cambios relevantes. + + +## 3. Pull Requests (PRs) + +### 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. + +### 3.2 Reglas generales para PRs + + * Cada PR debe abordar **un único objetivo claro**. + * Mantén el alcance lo más acotado posible. + * Incluye descripción clara del cambio. + * Si el PR corrige una *issue*, enlázala explícitamente. + * Asegúrate de que el código compila y pasa las pruebas. + +### 3.3 Revisión y aceptación + +Todas las PRs: + + * 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. + + +## 4. Autoría y atribución + +PageTop cuida especialmente la atribución de contribuciones. + + * 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. + + +## 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 + + * Sigue el estilo existente del proyecto. + * Mantén los comentarios claros y precisos. + * La documentación es parte del código: actualízala cuando sea necesario. + * Cambios públicos o estructurales deben ir acompañados de documentación. + + +## 8. Commits + +Recomendaciones generales: + + * 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. + +Durante la integración, los commits pueden ajustarse (rebase, squash o edición de mensajes) para +adaptarse al historial del proyecto. + +## 9. Comunicación y respeto + +PageTop sigue un enfoque profesional y colaborativo: + + * Sé respetuoso en revisiones y discusiones. + * Acepta sugerencias técnicas como parte del proceso. + * Recuerda que todas las contribuciones son revisadas con el objetivo de mejorar el proyecto. + + +## 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. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 00000000..fbf69db3 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,213 @@ +# 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 roles + +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**. + + +## 2. Configuración local recomendada + +Configuración típica de *remotes*: + +```bash +git remote -v +``` + +Ejemplo esperado: + +```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) +``` + +Convenciones usadas en este documento: + +* `origin` -> Oficial +* `github` -> GitHub (espejo) + + +## 3. Recepción de Pull Requests desde GitHub + +Las contribuciones externas llegan como *pull requests* en GitHub, normalmente contra `main`. + +### 3.1 Obtener la PR en local + +Opción habitual (ejemplo con PR #123): + +```bash +git fetch github pull/123/head:pr-123 +git checkout pr-123 +``` + +Alternativamente, si la rama del contribuidor es accesible directamente como referencia remota: + +```bash +git fetch github +git checkout nombre-de-la-rama +``` + + +## 4. Revisión local + +Antes de integrar cualquier cambio: + +* Revisar el código manualmente. +* Verificar compilación y pruebas: + +```bash +cargo build +cargo test +``` + +* 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. + +Procedimiento típico: + +```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: + +```bash +git push origin main +``` + +Este push representa **la integración definitiva**. + + +## 8. Cierre de la Pull Request en GitHub + +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: + +```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. +``` + + +## 9. Sincronización del repositorio oficial a GitHub + +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. + +--- + +Este documento puede evolucionar con el proyecto. +Su objetivo no es imponer rigidez, sino **capturar el conocimiento operativo real** de PageTop. diff --git a/README.md b/README.md index eceb5058..4c421edd 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ según las necesidades de cada proyecto, incluyendo: componentes sin comprometer su funcionalidad. -# ⚡️ Guía rápida +## ⚡️ Guía rápida La aplicación más sencilla de PageTop se ve así: @@ -74,7 +74,7 @@ Este programa implementa una extensión llamada `HelloWorld` que sirve una pági (`/`) mostrando el texto "Hello world!" dentro de un elemento HTML `

`. -# 📂 Repositorio +## 📂 Proyecto El código se organiza en un *workspace* donde actualmente se incluyen los siguientes subproyectos: @@ -82,7 +82,7 @@ El código se organiza en un *workspace* donde actualmente se incluyen los sigui fuente de la librería principal. Reúne algunos de los *crates* más estables y populares del ecosistema Rust para proporcionar APIs y recursos para la creación avanzada de soluciones web. -## Auxiliares +### Auxiliares * **[pagetop-build](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/helpers/pagetop-build)**, prepara los archivos estáticos o archivos SCSS compilados para incluirlos en el binario de las @@ -100,7 +100,7 @@ El código se organiza en un *workspace* donde actualmente se incluyen los sigui permite incluir archivos estáticos en el ejecutable de las aplicaciones PageTop para servirlos de forma eficiente, con detección de cambios que optimizan el tiempo de compilación. -## Extensiones +### Extensiones * **[pagetop-aliner](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-aliner)**, es un tema para demos y pruebas que muestra esquemáticamente la composición de las páginas HTML. @@ -110,7 +110,7 @@ El código se organiza en un *workspace* donde actualmente se incluyen los sigui componentes flexibles. -# 🧪 Pruebas +## 🧪 Pruebas Para simplificar el flujo de trabajo, el repositorio incluye varios **alias de Cargo** declarados en `.cargo/config.toml`. Basta con ejecutarlos desde la raíz del proyecto: @@ -127,14 +127,14 @@ Para simplificar el flujo de trabajo, el repositorio incluye varios **alias de C > Si quieres **activar** las trazas del registro de eventos entonces usa simplemente `cargo test`. -# 🚧 Advertencia +## 🚧 Advertencia **PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos hasta que se libere la versión **1.0.0**. -# 📜 Licencia +## 📜 Licencia El código está disponible bajo una doble licencia: @@ -148,7 +148,28 @@ Puedes elegir la licencia que prefieras. Este enfoque de doble licencia es el es el ecosistema Rust. -# ✨ Contribuir +## ✨ Contribuir + +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. + +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. + +Para conocer el proceso completo de participación, revisión e integración de cambios, consulta el +archivo [`CONTRIBUTING.md`](CONTRIBUTING.md). Cualquier contribución para añadir al proyecto se considerará automáticamente bajo la doble licencia indicada arriba (MIT o Apache v2.0), sin términos o condiciones adicionales, tal y como permite la diff --git a/extensions/pagetop-aliner/README.md b/extensions/pagetop-aliner/README.md index f4670aae..f3849122 100644 --- a/extensions/pagetop-aliner/README.md +++ b/extensions/pagetop-aliner/README.md @@ -12,14 +12,14 @@
-## Sobre PageTop +## 🧭 Sobre PageTop [PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y configurables, basadas en HTML, CSS y JavaScript. -# ⚡️ Guía rápida +## ⚡️ Guía rápida Igual que con otras extensiones, **añade la dependencia** a tu `Cargo.toml`: @@ -80,14 +80,14 @@ async fn homepage(request: HttpRequest) -> ResultPage { ``` -# 🚧 Advertencia +## 🚧 Advertencia **PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos hasta que se libere la versión **1.0.0**. -# 📜 Licencia +## 📜 Licencia El código está disponible bajo una doble licencia: diff --git a/extensions/pagetop-bootsier/README.md b/extensions/pagetop-bootsier/README.md index d6e1666a..e7a3ea79 100644 --- a/extensions/pagetop-bootsier/README.md +++ b/extensions/pagetop-bootsier/README.md @@ -12,14 +12,14 @@
-## Sobre PageTop +## 🧭 Sobre PageTop [PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y configurables, basadas en HTML, CSS y JavaScript. -# ⚡️ Guía rápida +## ⚡️ Guía rápida Igual que con otras extensiones, **añade la dependencia** a tu `Cargo.toml`: @@ -80,14 +80,14 @@ async fn homepage(request: HttpRequest) -> ResultPage { ``` -# 🚧 Advertencia +## 🚧 Advertencia **PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos hasta que se libere la versión **1.0.0**. -# 📜 Licencia +## 📜 Licencia El código está disponible bajo una doble licencia: diff --git a/helpers/pagetop-build/README.md b/helpers/pagetop-build/README.md index 875acbd9..c5d9c5bd 100644 --- a/helpers/pagetop-build/README.md +++ b/helpers/pagetop-build/README.md @@ -11,14 +11,14 @@ -## Sobre PageTop +## 🧭 Sobre PageTop [PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y configurables, basadas en HTML, CSS y JavaScript. -# ⚡️ Guía rápida +## ⚡️ Guía rápida Añadir en el archivo `Cargo.toml` del proyecto: @@ -30,7 +30,7 @@ pagetop-build = { ... } Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso: -## Incluir archivos estáticos desde un directorio +### Incluir archivos estáticos desde un directorio Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos: @@ -64,7 +64,7 @@ fn main() -> std::io::Result<()> { } ``` -## Compilar archivos SCSS a CSS +### Compilar archivos SCSS a CSS Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso con el archivo CSS minificado obtenido. Por ejemplo: @@ -83,7 +83,7 @@ Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, llamado `main_styles` que contiene el archivo `styles.min.css` obtenido. -# 📦 Archivos generados +## 📦 Archivos generados Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar [OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts) @@ -111,14 +111,14 @@ impl Extension for MyExtension { ``` -# 🚧 Advertencia +## 🚧 Advertencia **PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos hasta que se libere la versión **1.0.0**. -# 📜 Licencia +## 📜 Licencia El código está disponible bajo una doble licencia: diff --git a/helpers/pagetop-macros/README.md b/helpers/pagetop-macros/README.md index b7f1ad5e..9b0174a6 100644 --- a/helpers/pagetop-macros/README.md +++ b/helpers/pagetop-macros/README.md @@ -11,13 +11,14 @@ -## Sobre PageTop +## 🧭 Sobre PageTop [PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y configurables, basadas en HTML, CSS y JavaScript. -## Créditos + +## 📚 Créditos Este *crate* incluye entre sus macros una adaptación de [maud-macros](https://crates.io/crates/maud_macros) @@ -29,14 +30,14 @@ necesidad de referenciar `maud` o `smart_default` en las dependencias del archiv cada proyecto PageTop. -# 🚧 Advertencia +## 🚧 Advertencia **PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos hasta que se libere la versión **1.0.0**. -# 📜 Licencia +## 📜 Licencia El código está disponible bajo una doble licencia: diff --git a/helpers/pagetop-minimal/README.md b/helpers/pagetop-minimal/README.md index 16f73963..1f8ec148 100644 --- a/helpers/pagetop-minimal/README.md +++ b/helpers/pagetop-minimal/README.md @@ -11,19 +11,21 @@ -## Sobre PageTop +## 🧭 Sobre PageTop [PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y configurables, basadas en HTML, CSS y JavaScript. -## Descripción general + +## 🗺️ Descripción general Este *crate* proporciona un conjunto básico de macros que se integran en las utilidades de PageTop para optimizar operaciones habituales relacionadas con la composición estructurada de texto, la concatenación de cadenas y el uso rápido de colecciones clave-valor. -## Créditos + +## 📚 Créditos Las macros para texto multilínea **`indoc!`**, **`formatdoc!`** y **`concatdoc!`** se reexportan del *crate* [indoc](https://crates.io/crates/indoc) de [David Tolnay](https://crates.io/users/dtolnay). @@ -38,14 +40,14 @@ La macro para generar identificadores dinámicos **`paste!`** se reexporta del * `paste!` de [David Tolnay](https://crates.io/users/dtolnay). -# 🚧 Advertencia +## 🚧 Advertencia **PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos hasta que se libere la versión **1.0.0**. -# 📜 Licencia +## 📜 Licencia El código está disponible bajo una doble licencia: diff --git a/helpers/pagetop-statics/README.md b/helpers/pagetop-statics/README.md index 99e24b4d..7466dc1f 100644 --- a/helpers/pagetop-statics/README.md +++ b/helpers/pagetop-statics/README.md @@ -11,19 +11,21 @@ -## Sobre PageTop +## 🧭 Sobre PageTop [PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y configurables, basadas en HTML, CSS y JavaScript. -## Descripción general + +## 🗺️ Descripción general Este *crate* permite incluir archivos estáticos en el ejecutable de las aplicaciones PageTop para servirlos de forma eficiente vía web, con detección de cambios que optimizan el tiempo de compilación. -## Créditos + +## 📚 Créditos Para ello, adapta el código de los *crates* [static-files](https://crates.io/crates/static_files) (versión [0.2.5](https://github.com/static-files-rs/static-files/tree/v0.2.5)) y @@ -35,14 +37,14 @@ Estas implementaciones se integran en PageTop para evitar que cada proyecto teng `static-files` manualmente como dependencia en su `Cargo.toml`. -# 🚧 Advertencia +## 🚧 Advertencia **PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos hasta que se libere la versión **1.0.0**. -# 📜 Licencia +## 📜 Licencia El código está disponible bajo una doble licencia: