🤝Guía de Contribución - ToLearn

¡Gracias por tu interés en contribuir a ToLearn! Esta guía te ayudará a realizar contribuciones de manera efectiva.

📋 Tabla de Contenidos

• Código de Conducta

• Cómo Contribuir

• Proceso de Pull Request

• Reportar Bugs

• Sugerir Mejoras

• Guía de Estilo

• Estructura de Commits

• Comunidad

📜 Código de Conducta

Nuestro Compromiso

Nos comprometemos a hacer de la participación en nuestro proyecto una experiencia libre de acoso para todos, independientemente de:

• Edad

• Tamaño corporal

• Discapacidad visible o invisible

• Etnicidad

• Características sexuales

• Identidad y expresión de género

• Nivel de experiencia

• Educación

• Estatus socioeconómico

• Nacionalidad

• Apariencia personal

• Raza

• Religión

• Identidad y orientación sexual

Comportamiento Esperado

✅ Hacer:

• Usar lenguaje acogedor e inclusivo

• Respetar puntos de vista y experiencias diferentes

• Aceptar críticas constructivas con gracia

• Enfocarse en lo mejor para la comunidad

• Mostrar empatía hacia otros miembros

❌ No Hacer:

• Usar lenguaje o imágenes sexualizadas

• Hacer comentarios insultantes o despectivos

• Acosar públicamente o privadamente

• Publicar información privada sin permiso

• Otras conductas no profesionales

Aplicación

Los administradores del proyecto son responsables de aclarar y hacer cumplir estos estándares. Tomarán acciones correctivas apropiadas en respuesta a cualquier comportamiento inaceptable.

🎯 Cómo Contribuir

Tipos de Contribuciones

1. Reportar Bugs 🐛

¿Encontraste un error? Ayúdanos reportándolo.

2. Sugerir Funcionalidades 💡

¿Tienes una idea para mejorar ToLearn? Compártela.

3. Mejorar Documentación 📚

La documentación siempre puede mejorar.

4. Escribir Código 💻

Implementa nuevas funcionalidades o arregla bugs.

5. Revisar Pull Requests 👀

Ayuda revisando código de otros contribuidores.

6. Traducir 🌍

Ayuda a traducir la plataforma a más idiomas.

Primeros Pasos

1. Fork el Repositorio

   # Click en "Fork" en GitHub
   # Luego clona tu fork
   git clone https://github.com/TU-USUARIO/Tolearn.git
   cd Tolearn

2. Configurar Upstream

   git remote add upstream https://github.com/dpalik500/Tolearn.git
   git fetch upstream

3. Crear Rama de Trabajo

   git checkout -b feature/mi-nueva-funcionalidad
   # o
   git checkout -b fix/corregir-bug

4. Configurar Entorno

   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   python manage.py migrate

Áreas que Necesitan Ayuda

Busca issues con las siguientes etiquetas:

• good first issue - Perfecto para principiantes

• help wanted - Necesitamos ayuda

• bug - Bugs reportados

• enhancement - Nuevas funcionalidades

• documentation - Mejoras de documentación

🔄 Proceso de Pull Request

Antes de Empezar

1. Busca issues existentes

   • Revisa si alguien más ya está trabajando en ello

   • Comenta en el issue para indicar que trabajarás en ello

2. Discute cambios grandes

   • Para funcionalidades grandes, abre un issue primero

   • Discute el diseño antes de invertir mucho tiempo

Hacer el Pull Request

1. Realiza tus Cambios

# Edita archivos
nano courses/models.py

# Asegúrate de seguir las guías de estilo
flake8 .
black .

2. Escribe Tests

# courses/tests.py
def test_nueva_funcionalidad():
    """Test para mi nueva funcionalidad"""
    # Tu test aquí
    assert True

Ejecuta tests:

pytest

3. Actualiza Documentación

Si tu cambio afecta la funcionalidad pública:

• Actualiza docstrings

• Actualiza README si es necesario

• Agrega ejemplos de uso

4. Commit tus Cambios

git add .
git commit -m "feat: agregar nueva funcionalidad X"

# Sigue la convención de commits (ver abajo)

5. Push a tu Fork

git push origin feature/mi-nueva-funcionalidad

6. Crear Pull Request

1. Ve a GitHub

2. Click en "New Pull Request"

3. Selecciona tu rama

4. Llena la plantilla del PR (ver abajo)

Plantilla de Pull Request

## Descripción
Breve descripción del cambio y su motivación.

## Tipo de Cambio
- [ ] Bug fix (cambio que corrige un issue)
- [ ] Nueva funcionalidad (cambio que agrega funcionalidad)
- [ ] Breaking change (cambio que rompe compatibilidad)
- [ ] Documentación

## ¿Cómo se ha probado?
Describe las pruebas realizadas.

- [ ] Test A
- [ ] Test B

## Checklist
- [ ] Mi código sigue el estilo del proyecto
- [ ] He realizado una auto-revisión de mi código
- [ ] He comentado código complejo
- [ ] He actualizado la documentación
- [ ] Mis cambios no generan nuevos warnings
- [ ] He agregado tests que prueban mi cambio
- [ ] Tests nuevos y existentes pasan localmente

## Screenshots (si aplica)
Agrega capturas de pantalla si hay cambios visuales.

## Issues Relacionados
Fixes #123
Relates to #456

Proceso de Revisión

1. Revisión Automática

   • CI ejecuta tests automáticamente

   • Verifica linters y formateo

2. Revisión por Pares

   • Al menos un maintainer revisará tu código

   • Puede solicitar cambios

3. Hacer Cambios Solicitados

   # Hacer cambios
   git add .
   git commit -m "fix: corregir comentarios de revisión"
   git push origin feature/mi-nueva-funcionalidad

4. Merge

   • Una vez aprobado, un maintainer hará merge

   • Tu contribución aparecerá en el proyecto

🐛 Reportar Bugs

Antes de Reportar

• Busca en issues existentes

• Verifica que usas la última versión

• Confirma que es un bug y no un problema de configuración

Cómo Reportar

Crea un nuevo issue con la siguiente información:

**Descripción del Bug**
Una descripción clara del bug.

**Pasos para Reproducir**
1. Ve a '...'
2. Haz click en '...'
3. Observa el error

**Comportamiento Esperado**
Lo que debería suceder.

**Comportamiento Actual**
Lo que realmente sucede.

**Screenshots**
Si aplica, agrega screenshots.

**Entorno:**
- OS: [ej. Ubuntu 20.04]
- Python: [ej. 3.10]
- Django: [ej. 5.2.4]
- Navegador: [ej. Chrome 120]

**Contexto Adicional**
Cualquier información adicional.

**Logs/Errores**

Pega logs de error aquí

💡 Sugerir Mejoras

Tipos de Sugerencias

1. Nuevas Funcionalidades

   • Describe el problema que resuelve

   • Explica la solución propuesta

   • Considera alternativas

2. Mejoras de UX/UI

   • Explica el problema actual

   • Proporciona mockups si es posible

   • Considera impacto en usuarios

3. Mejoras de Rendimiento

   • Identifica el cuello de botella

   • Proporciona benchmarks si es posible

   • Sugiere optimización

Plantilla de Feature Request

**¿Tu feature request está relacionada a un problema?**
Una descripción clara del problema. Ej. "Siempre me frustro cuando..."

**Describe la solución que te gustaría**
Descripción clara de lo que quieres que suceda.

**Describe alternativas que has considerado**
Otras soluciones o funcionalidades consideradas.

**Contexto Adicional**
Screenshots, mockups, ejemplos de otras plataformas, etc.

**¿Estarías dispuesto a implementarlo?**
- [ ] Sí, puedo trabajar en esto
- [ ] Necesitaría ayuda
- [ ] Solo estoy sugiriendo

🎨 Guía de Estilo

Python

Seguimos PEP 8 con adaptaciones:

# Longitud máxima de línea: 120 caracteres
# Usar black para formateo automático
black .

# Usar flake8 para linting
flake8 .

# Usar isort para ordenar imports
isort .

Django Específico

# Imports
from django.db import models  # Django primero
from django.contrib.auth.models import User
from .models import Course  # Locales al final

# Modelos
class Course(models.Model):
    """Docstring describiendo el modelo."""
    
    title = models.CharField(max_length=255)
    
    class Meta:
        verbose_name = 'Curso'
        verbose_name_plural = 'Cursos'
        ordering = ['title']
    
    def __str__(self):
        return self.title
    
    def get_absolute_url(self):
        return reverse('course_detail', args=[self.pk])

# Vistas
def my_view(request):
    """Docstring describiendo la vista."""
    context = {
        'title': 'Mi Página',
    }
    return render(request, 'template.html', context)

JavaScript

// Usar camelCase para variables y funciones
const userName = 'Juan';
function getUserCourses(userId) {
    // ...
}

// Usar PascalCase para clases
class ExamController {
    constructor(examId) {
        this.examId = examId;
    }
}

// Usar const/let, no var
const API_URL = '/api/v1/';
let currentPage = 1;

// Arrow functions cuando sea apropiado
const square = x => x * x;

// Async/await para promesas
async function fetchCourses() {
    const response = await fetch('/courses/');
    return await response.json();
}

CSS/HTML

<!-- Usar semantic HTML -->
<article class="course-card">
    <header>
        <h2>Título del Curso</h2>
    </header>
    <section class="course-content">
        <p>Contenido...</p>
    </section>
</article>

<!-- Usar clases descriptivas -->
<button class="btn btn-primary btn-lg">
    Inscribirse
</button>

/* BEM para clases CSS */
.course-card { }
.course-card__title { }
.course-card__content { }
.course-card--featured { }

/* Mobile-first */
.container {
    width: 100%;
}

@media (min-width: 768px) {
    .container {
        max-width: 720px;
    }
}

📝 Estructura de Commits

Usamos Conventional Commits:

Formato

<tipo>(<alcance>): <descripción>

<cuerpo opcional>

<footer opcional>

Tipos

• feat: Nueva funcionalidad

• fix: Corrección de bug

• docs: Cambios en documentación

• style: Cambios de formato (no afectan código)

• refactor: Refactorización de código

• test: Agregar o modificar tests

• chore: Tareas de mantenimiento

• perf: Mejoras de rendimiento

Ejemplos

# Funcionalidad nueva
git commit -m "feat(courses): agregar filtro de cursos por categoría"

# Corrección de bug
git commit -m "fix(dashboard): corregir cálculo de calificación"

# Documentación
git commit -m "docs(api): actualizar documentación de endpoints"

# Refactorización
git commit -m "refactor(webinar): simplificar lógica de WebSocket"

# Tests
git commit -m "test(courses): agregar tests para modelo Course"

# Con breaking change
git commit -m "feat(api): cambiar formato de respuesta

BREAKING CHANGE: la respuesta de /api/courses/ ahora es un objeto en lugar de array"

Alcance

El alcance especifica qué parte del código se afecta:

• courses - Sistema de cursos

• dashboard - Panel de control

• webinar - Sistema de webinars

• auth - Autenticación

• api - API endpoints

• admin - Panel administrativo

• docs - Documentación

👥 Comunidad

Canales de Comunicación

• GitHub Issues: Bugs y feature requests

• GitHub Discussions: Preguntas y discusiones generales

• Email: [email protected]

Reconocimientos

Reconocemos a todos los contribuidores en:

• README.md

• CONTRIBUTORS.md (si existe)

• Release notes

Niveles de Contribución

Contributor

• Ha realizado al menos una contribución aceptada

Regular Contributor

• 5+ contribuciones aceptadas

• Ayuda en revisiones de PR

• Participa activamente en discusiones

Core Contributor

• 20+ contribuciones significativas

• Experiencia profunda en el proyecto

• Ayuda a mantener el proyecto

Maintainer

• Responsable de revisión y merge de PRs

• Toma decisiones sobre roadmap

• Administra el repositorio

🎓 Recursos para Nuevos Contribuidores

Tutoriales

• First Contributions

• How to Contribute to Open Source

• GitHub Flow

Documentación

• Django Documentation

• Python Style Guide

• Git Documentation

Herramientas

• GitHub Desktop - Cliente Git visual

• VS Code - Editor recomendado

• PyCharm - IDE Python

❓ Preguntas Frecuentes

P: ¿Necesito saber Django para contribuir? R: No necesariamente. Puedes contribuir con documentación, traduciones, reportar bugs, etc.

P: ¿Cuánto tiempo toma que revisen mi PR? R: Típicamente 2-7 días. Si no recibes respuesta en una semana, comenta en el PR.

P: ¿Puedo trabajar en múltiples issues a la vez? R: Sí, pero recomendamos enfocarte en uno a la vez para mantener la calidad.

P: ¿Qué hago si mi PR no es aceptado? R: No te desanimes. Revisa los comentarios, aprende de ellos, y sigue contribuyendo.

P: ¿Dónde encuentro issues para principiantes? R: Busca el label good first issue en GitHub Issues.

📜 Licencia

Al contribuir a ToLearn, aceptas que tus contribuciones serán licenciadas bajo la misma licencia del proyecto (MIT License).

---

🙏 Agradecimientos

¡Gracias por considerar contribuir a ToLearn! Cada contribución, sin importar su tamaño, es valiosa y apreciada.

Juntos estamos construyendo una mejor plataforma educativa para todos. 🎓✨

---

¿Listo para contribuir?

1. Encuentra un issue

2. Comenta que trabajarás en él

3. Fork el repo

4. Haz tus cambios

5. Envía un PR

¡Esperamos tu contribución! 🚀