Guía de Contribución al Proyecto

¡Gracias por tu interés en contribuir a este proyecto! Esta guía te ayudará a entender el proceso de contribución, asegurando que tus aportes sean fluidos y seguros. Aprenderás a configurar tu entorno de desarrollo, a realizar cambios siguiendo las mejores prácticas y a resolver problemas comunes, especialmente aquellos relacionados con la seguridad de la información.

🔒 Requisitos de Seguridad

Este repositorio cuenta con verificaciones de seguridad para prevenir la subida accidental de claves privadas e información sensible.

Configuración Requerida

Antes de realizar cualquier commit, debes instalar los "pre-commit hooks". Estos son scripts que se ejecutan automáticamente antes de cada commit para verificar el código.

Este comando instala las herramientas de pre-commit y configura los hooks definidos en el repositorio. Es un paso crucial para mantener la seguridad del proyecto.

# Install pre-commit
pip install pre-commit

# Install the hooks for this repository
pre-commit install

¿Qué sucede si no lo haces?

• Tus commits serán bloqueados localmente si contienen claves privadas. Los hooks detectarán la información sensible antes de que el commit se complete.
• Las Pull Requests (PRs) con claves privadas fallarán las verificaciones de Integración Continua (CI) y no podrán ser fusionadas. Esto asegura que ninguna información sensible llegue al repositorio principal.
• Esto protege a todos de exponer accidentalmente información sensible. La seguridad es una responsabilidad compartida.

🚀 Cómo Empezar

Sigue estos pasos para configurar tu entorno y empezar a contribuir al proyecto.

1. Haz un "fork" del repositorio

   Un "fork" crea una copia del repositorio en tu cuenta de GitHub, permitiéndote experimentar con cambios sin afectar el proyecto original.

2. Clona tu "fork"

   Este comando descarga tu copia del repositorio a tu máquina local, para que puedas trabajar en los archivos.

   git clone https://github.com/<YOUR-USERNAME>/cookbook.git
   cd cookbook
   

3. Configura los "pre-commit hooks" (¡requerido!)

   Como se mencionó anteriormente, este paso es fundamental para asegurar que tus contribuciones cumplan con los estándares de seguridad del proyecto.

   pip install pre-commit
   pre-commit install
   

4. Crea una nueva rama

   Trabajar en una rama separada te permite desarrollar nuevas características o corregir errores sin afectar la rama principal del proyecto. El nombre de la rama debe ser descriptivo.

   git checkout -b <YOUR BRANCH NAME>
   

5. Realiza tus cambios

   Aquí es donde implementas las nuevas características, corriges errores o mejoras la documentación. Asegúrate de que tus cambios sean claros y bien documentados.

6. Prueba tus cambios

   Antes de enviar tus cambios, es vital que los pruebes localmente para asegurarte de que funcionan como se espera y no introducen nuevos errores.

   # Run security check manually (optional)
   pre-commit run detect-private-key --all-files
   

7. Haz "commit" y "push"

   Este comando guarda tus cambios en tu rama local y luego los sube a tu repositorio "fork" en GitHub. Asegúrate de que tu mensaje de commit sea claro y conciso.

   git add .
   git commit -m "Your commit message"
   git push origin <YOUR BRANCH NAME>
   

8. Crea una Pull Request (PR)

   Una vez que tus cambios estén en tu "fork", puedes abrir una Pull Request desde tu rama a la rama principal del repositorio original. Esto permitirá que los mantenedores del proyecto revisen tus cambios y los fusionen.

⚠️ Problemas Comunes

Error "Private key detected"

Si ves este error al hacer un commit, significa que los "pre-commit hooks" han detectado información sensible en tus archivos. Es crucial abordar esto antes de continuar.

detect-private-key...........................................................Failed

• Elimina cualquier clave privada, clave de API o información sensible de tus archivos. Nunca deben ser parte del código fuente.
• Revisa archivos como .env, archivos de configuración o cualquier archivo que contenga credenciales. Estos son lugares comunes donde se pueden almacenar accidentalmente datos sensibles.
• Usa variables de entorno o bóvedas seguras para datos sensibles en su lugar. Esta es la práctica recomendada para manejar credenciales de forma segura.

Mejores Prácticas

Seguir estas mejores prácticas te ayudará a contribuir de manera efectiva y segura al proyecto.

• Nunca hagas commit de claves privadas, claves de API, contraseñas u otra información sensible. Esto es fundamental para la seguridad del proyecto y de tus propias credenciales.
• Usa variables de entorno para la configuración. Esto permite que la configuración cambie fácilmente entre diferentes entornos (desarrollo, producción) sin modificar el código.
• Mantén los datos sensibles en archivos .env y agrégalos a .gitignore. El archivo .gitignore asegura que estos archivos nunca sean subidos al repositorio.
• Prueba tus cambios localmente antes de crear una PR. Esto ayuda a identificar y corregir errores temprano, ahorrando tiempo a los revisores.

Resumen

• Instala los "pre-commit hooks" para asegurar la detección de información sensible antes de cada commit.
• Sigue el flujo de trabajo estándar: "fork", "clone", crea una rama, realiza cambios, prueba, "commit" y "push", y finalmente crea una Pull Request.
• Evita el error "Private key detected" eliminando cualquier credencial de tus archivos y usando variables de entorno.
• Adopta las mejores prácticas de seguridad, como no hacer commit de claves privadas y usar .gitignore para archivos sensibles.