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