# 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

> ⚠️ **Importante**
> 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)

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**, normalmente 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 son **revisadas manualmente** y pueden recibir comentarios o solicitudes de cambios.

Las PRs aceptadas se integran en el repositorio oficial, nunca directamente en GitHub, preservando
siempre la **autoría original** del contribuidor.


### 3.4. Cierre de Pull Requests y sincronización

Una vez que el cambio ha sido integrado en el repositorio oficial:

  * 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.


## 4. 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.


## 5. Commits

PageTop usa la especificación **gitmoji** para los mensajes de *commit*. El formato recomendado es:

  ```text
  <propósito> [(ámbito opcional):] <mensaje>
  «LÍNEA EN BLANCO»
  Cuerpo opcional
  «LÍNEA EN BLANCO»
  Nota(s) al pie opcional(es) para referencias, incidencias o cambios incompatibles
  ```

Ejemplos (no más de 50 caracteres en la primera línea, y no más de 80 en el resto):

  * `📝 Actualiza la guía de contribución`
  * `♻️ (locale): Refactoriza sistema de localización`
  * Un mensaje completo:
    ```
    🎨 (bootsier): Mejora la asignación de clases

    - Simplifica la generación de clases CSS para componentes Bootstrap.
    - Elimina duplicidades en enums de estilos y centraliza la lógica de composición
      para reducir errores y facilitar mantenimiento.
    - Alinea los nombres de variantes con la documentación pública.

    Refs: PR #123
    ```

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:

  * 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.

Si tienes dudas sobre el proceso, abre una *issue* de tipo pregunta para tratar la cuestión en
comunidad.

---

Gracias por contribuir a **PageTop** 🚀 Cada aportación contribuye a mejorar el proyecto.