Guía para Contribuidores - SunNeurotron/Aletheia GitHub Wiki

Guía para Contribuidores de Aletheia

¡Bienvenido y gracias por tu interés en contribuir a Aletheia! Este proyecto es de código abierto y agradecemos cualquier contribución, desde la corrección de erratas en la documentación hasta la implementación de nuevas características complejas.

Para mantener la calidad y la coherencia del proyecto, por favor sigue estas directrices.

Código de Conducta

Se espera que todos los contribuidores se adhieran a nuestro Código de Conducta. El objetivo es fomentar una comunidad abierta, respetuosa y acogedora para todos.

Cómo Contribuir

Existen varias formas de contribuir al proyecto:

  • Reportando Bugs: Si encuentras un error, por favor abre una nueva Issue utilizando la plantilla de "Bug Report". Describe claramente el problema, los pasos para reproducirlo y el comportamiento esperado vs. el real.
  • Sugiriendo Mejoras: Si tienes una idea para una nueva característica, abre una nueva Issue utilizando la plantilla de "Feature Request" para iniciar una discusión con la comunidad.
  • Escribiendo Código: Si quieres solucionar un bug o implementar una nueva característica, por favor sigue el flujo de trabajo que se describe a continuación.

Flujo de Trabajo para Contribuciones de Código

Seguimos el modelo estándar de "Fork y Pull Request" de GitHub, que es una práctica recomendada para proyectos de código abierto.

  1. Haz un Fork del Repositorio: Haz clic en el botón "Fork" en la esquina superior derecha para crear una copia del proyecto en tu propia cuenta de GitHub.

  2. Clona tu Fork: Clona tu copia del repositorio a tu máquina local para poder trabajar en los archivos.

    git clone https://github.com/TU-PROPIO-USUARIO/Aletheia.git
cd Aletheia

  3. Configura el Entorno de Desarrollo: El proyecto utiliza Docker para gestionar todas las dependencias y servicios. La forma más fácil de configurar tu entorno es utilizando Docker Compose.

    # Levanta todos los servicios (API, DB, Worker, etc.) en segundo plano
docker-compose up --build -d

    Esto asegurará que tienes un entorno idéntico al de producción para desarrollar y probar.

  4. Crea una Nueva Rama (Branch): Es crucial trabajar en una rama separada para cada nueva característica o corrección. Esto mantiene el historial limpio.

    # Ejemplo para una nueva característica
git checkout -b feature/add-new-visualization

# Ejemplo para una corrección de error
git checkout -b fix/dashboard-refresh-bug

  5. Escribe tu Código: Realiza los cambios necesarios en tu editor de código preferido. Asegúrate de seguir los estándares de código del proyecto (formato con black, tipado estático, etc.).

  6. Ejecuta los Tests: Antes de enviar tu contribución, asegúrate de que todos los tests existentes pasan y, si es aplicable, añade nuevos tests para tu código.

    # Ejecuta la suite de tests dentro del contenedor de la API
docker-compose exec api pytest

  7. Haz Commit de tus Cambios: Usa mensajes de commit claros y descriptivos, siguiendo el estándar de Conventional Commits para mantener un historial legible.

    # Ejemplo de commit para una nueva característica
git commit -m "feat: Añadir gráfico de dispersión 3D al dashboard"

# Ejemplo de commit para una corrección de error
git commit -m "fix: Corregir el refresco automático del estado de los trabajos"

  8. Haz Push a tu Fork: Sube los cambios de tu rama a tu repositorio en GitHub.

    git push origin feature/add-new-visualization

  9. Abre un Pull Request (PR):

    • Ve a tu fork en GitHub.
    • Verás un banner sugiriendo crear un Pull Request desde tu nueva rama. Haz clic en él.
    • Asegúrate de que la base sea el repositorio original (tu-usuario-original/Aletheia) y la rama de comparación sea tu nueva rama.
    • Escribe un título claro y una descripción detallada de los cambios que has realizado. Si tu PR resuelve una Issue existente, enlázala usando la palabra clave Closes #123.
    • Envía el Pull Request para su revisión. Uno de los mantenedores del proyecto lo revisará y te dará su feedback.