Cómo Contribuir

¡Nos encanta escuchar ideas de nuestros usuarios! Es lo que hace que esta plataforma sea tan excelente y versátil. ¡Si tienes una idea para contribuir, tómate un momento para compartirla con nosotros!

El proyecto recibe, y depende de, contribuciones de desarrolladores y usuarios de la comunidad de código abierto. Las contribuciones se pueden hacer de varias formas:

• Parches de código a través de solicitudes de extracción
• Mejoras de documentación
• Reportes de errores y revisión de parches

Primeros Pasos

1. Lee esta página completa de “arriba a abajo”.
2. Asegúrate de tener una cuenta de GitHub.
3. Preséntate en el chat de desarrolladores en Discord.
4. Echa un vistazo a la página Problemas Abiertos. Hemos hecho que sea fácil para principiantes con la etiqueta good first issue — estos son problemas que deberían ser relativamente fáciles de resolver.
5. ¡Diviértete!

Configuración del Entorno de Desarrollo

Inicio Rápido (Recomendado)

🚀 GitHub Codespaces (Lo Más Fácil):

1. Haz clic en “Code” → “Codespaces” → “Create codespace on [branch]”
2. Espera 2-3 minutos para la configuración automática
3. Abre http://localhost e inicia sesión con admin/changeme

🐳 Contenedores de Desarrollo VS Code:

1. Instala la extensión “Dev Containers” en VS Code
2. Abre este repositorio en VS Code
3. Haz clic en “Reopen in Container” cuando se solicite
4. Espera a que se complete la configuración

🔧 DDEV (Docker Local):

1. Instala DDEV y Docker
2. Clona el repositorio y ejecuta:

   git clone https://github.com/ChurchCRM/CRM.git churchcrm
   cd churchcrm
   ddev start
   ddev setup-churchcrm
   

3. Abre https://churchcrm.ddev.site e inicia sesión con admin/changeme

Ver Configuración DDEV abajo para detalles completos y solución de problemas.

Configuración Manual

Si prefieres instalar manualmente o las opciones automáticas no funcionan:

1. Instalar Requisitos Previos:

   • Git (o GitHub Desktop)
   • Node.js versión 20+
   • Docker
   • PHP 8.4+ con extensiones: bcmath, curl, gd, gettext, iconv, mbstring, mysqli, pdo_mysql, sodium, zip, zlib
   • Composer (gestor de dependencias PHP)

2. Clonar y Configurar:

   git clone https://github.com/tu-usuario/ChurchCRM.git
   cd ChurchCRM
   ./scripts/setup-dev-environment.sh
   

3. Acceder al Sitio Web:

   • ChurchCRM: http://localhost/ (admin/changeme)
   • MailHog: http://localhost:8025 (prueba de correo)
   • Adminer: http://localhost:8088 (administrador de base de datos)

Solución de Problemas

Problemas Comunes:

• Conflictos de puerto 80: Detén otros servidores web o cambia la asignación de puertos Docker
• Error en la construcción de Docker: Asegúrate de que Docker tenga 4GB+ de memoria asignada
• Servicios no iniciando: Ejecuta npm run docker:dev:logs para verificar registros
• Pruebas fallando localmente: Usa npm run docker:test:rebuild para un entorno de prueba limpio
• Extensiones PHP faltantes: Usa contenedores Docker - no construyas localmente
• Esquema de base de datos desactualizado: Ejecuta npm run docker:test:restart:db para refrescar

Configuración DDEV

DDEV es un entorno de desarrollo local basado en Docker que te proporciona PHP, MariaDB, Node.js, HTTPS y pruebas de correo con un solo comando.

Requisitos Previos

• Docker Desktop
• DDEV v1.22+

Inicio Rápido

git clone https://github.com/ChurchCRM/CRM.git churchcrm
cd churchcrm
ddev start
ddev setup-churchcrm
ddev launch

Inicio de sesión: admin / changeme

URLs de Servicios

Flujo de Trabajo Diario

ddev start                        # Iniciar servicios
ddev stop                         # Detener servicios
ddev ssh                          # Acceso a shell
ddev logs                         # Ver registros

Solución de Problemas DDEV

Documentación completa de DDEV: https://ddev.readthedocs.io

Estándares de Desarrollo

Interfaz de Usuario

ChurchCRM utiliza el framework AdminLTE para la interfaz de usuario. Sigue estas directrices:

1. Familiarízate con AdminLTE
2. Mantén los cambios de UI alineados con los principios de diseño de AdminLTE
3. Crea archivos CSS modulares y organizados para estilos personalizados
4. Asegura el diseño responsivo en todos los tamaños de pantalla

Arquitectura Slim MVC

Para nuevas APIs y páginas, sigue la arquitectura Slim MVC (Modelo-Vista-Controlador).

Pruebas con Cypress

Usa Cypress para pruebas de principio a fin:

npm run test              # Ejecutar todas las pruebas
npm run test:ui           # Pruebas interactivas

Estructura de pruebas:

• Pruebas de API: cypress/e2e/api/private/[feature]/[endpoint].spec.js
• Pruebas de UI: cypress/e2e/ui/[feature]/

Flujo de Trabajo de Desarrollo

1. Ramificación:

   git checkout -b nombre-feature
   

2. Estándares de Código:

   • Sigue los estándares de codificación existentes
   • Adhiérete a la guía de estilos en .github/copilot-instructions.md
   • Usa mensajes de confirmación descriptivos

3. Pruebas:

   • Escribe pruebas para tus cambios usando Cypress
   • Actualiza la documentación según sea necesario

4. Proceso de Solicitud de Extracción:

   git pull origin master
   git rebase master
   git push origin nombre-feature
   

Estándares de Codificación

ChurchCRM mantiene estándares de calidad de código estrictos:

• ✅ Base de Datos: ORM Propel obligatorio (sin SQL crudo)
• ✅ HTML5: Solo CSS Bootstrap 4.6.2
• ✅ Servicios: Lógica empresarial en clases Service
• ✅ PHP 8.4+: Tipos anulables explícitos
• ✅ i18n: Envuelve el texto de UI con gettext() o i18next.t()

Para estándares completos, ver .github/copilot-instructions.md

Código de Conducta

Por favor, adhiérate al Código de Conducta en todas las interacciones.

¡Gracias por tu contribución!