Saltearse al contenido
DiscordBot-TK

Contribuir

🤝 Contribuir al Proyecto

¡Gracias por tu interés en contribuir a DiscordBot-TK! Esta guía te ayudará a empezar y te explicará cómo puedes ayudar a mejorar el proyecto.

🎯 Formas de Contribuir

🐛 Reportar Bugs

  • Usa el sistema de Issues en GitHub
  • Incluye pasos para reproducir el problema
  • Proporciona logs y capturas de pantalla
  • Especifica versión del bot y entorno

💡 Sugerir Funcionalidades

  • Crea un Feature Request en GitHub
  • Explica el caso de uso y beneficios
  • Proporciona mockups o ejemplos si es posible
  • Discute la implementación con el equipo

🔧 Contribuir con Código

  • Fork del repositorio
  • Crear rama de feature
  • Implementar cambios
  • Crear Pull Request

📚 Mejorar Documentación

  • Corregir errores tipográficos
  • Agregar ejemplos y casos de uso
  • Traducir a nuevos idiomas
  • Mejorar explicaciones técnicas

🌍 Traducciones

  • Agregar soporte para nuevos idiomas
  • Mejorar traducciones existentes
  • Validar consistencia de traducciones

🚀 Configuración del Entorno de Desarrollo

Prerrequisitos

Ventana de terminal
# Node.js v18 o superior
node --version


# PNPM (recomendado) o NPM
pnpm --version


# Git
git --version

Configuración Inicial

  1. Fork y Clone

    Ventana de terminal
    # Fork el repositorio en GitHub
    git clone https://github.com/tu-usuario/discordbot-tk.git
    cd discordbot-tk

  2. Instalar Dependencias

    Ventana de terminal
    pnpm install

  3. Configurar Variables de Entorno

    Ventana de terminal
    cp .env.example .env
    # Editar .env con tus tokens de desarrollo

  4. Configurar Bot de Desarrollo

    • Crear aplicación en Discord Developer Portal
    • Obtener token y Client ID
    • Invitar bot a servidor de pruebas

  5. Inicializar Base de Datos

    Ventana de terminal
    # La base de datos se crea automáticamente al iniciar
    pnpm dev

Estructura para Desarrollo

discordbot-tk/
├── .github/           # Workflows y templates
├── src/               # Código fuente
├── tests/             # Tests automatizados
├── docs/              # Documentación
├── scripts/           # Scripts de utilidad
└── .dev/              # Archivos de desarrollo
    ├── test-guild/    # Configuración de servidor de pruebas
    └── fixtures/      # Datos de prueba

📝 Estándares de Código

Estilo de Código

// ✅ Bueno
const { SlashCommandBuilder } = require('discord.js');
const { getTranslation } = require('../../utils/i18n');


module.exports = {
  data: new SlashCommandBuilder()
    .setName('ejemplo')
    .setDescription('Comando de ejemplo'),


  async execute(interaction) {
    try {
      const t = await getTranslation(interaction.guild.id);


      await interaction.reply({
        content: t('commands.ejemplo.response'),
        ephemeral: true
      });
    } catch (error) {
      console.error('Error en comando ejemplo:', error);
      await interaction.reply({
        content: 'Ocurrió un error.',
        ephemeral: true
      });
    }
  }
};

Convenciones de Nombres

// Archivos y directorios
comando-ejemplo.js          // kebab-case
ManejadorEjemplo.js         // PascalCase para clases


// Variables y funciones
const miVariable = 'valor';  // camelCase
function miFuncion() {}      // camelCase


// Constantes
const MI_CONSTANTE = 'valor'; // SCREAMING_SNAKE_CASE


// Clases
class MiClase {}             // PascalCase

Manejo de Errores

// ✅ Siempre manejar errores
try {
  await rieskyOperation();
} catch (error) {
  Logger.error('Error específico', { error, context });
  // Manejar gracefully
}


// ✅ Usar logging apropiado
Logger.info('Operación exitosa', { details });
Logger.warn('Situación atípica', { context });
Logger.error('Error crítico', { error });


// ✅ Respuestas de error amigables
await interaction.reply({
  content: t('errors.unexpectedError'),
  ephemeral: true
});

🧪 Testing

Estructura de Tests

tests/
├── unit/              # Tests unitarios
│   ├── utils/         # Tests de utilidades
│   ├── handlers/      # Tests de handlers
│   └── commands/      # Tests de comandos
├── integration/       # Tests de integración
│   ├── database/      # Tests de BD
│   └── discord/       # Tests con Discord API
├── e2e/              # Tests end-to-end
└── fixtures/         # Datos de prueba

Ejemplo de Test Unitario

tests/unit/utils/text.test.js
const { TextUtils } = require('../../../src/utils/text');


describe('TextUtils', () => {
  describe('truncate', () => {
    test('should truncate long text', () => {
      const text = 'Este es un texto muy largo';
      const result = TextUtils.truncate(text, 10);
      expect(result).toBe('Este es...');
    });


    test('should not truncate short text', () => {
      const text = 'Corto';
      const result = TextUtils.truncate(text, 10);
      expect(result).toBe('Corto');
    });
  });


  describe('capitalize', () => {
    test('should capitalize first letter', () => {
      const result = TextUtils.capitalize('hello world');
      expect(result).toBe('Hello world');
    });
  });
});

Ejecutar Tests

Ventana de terminal
# Todos los tests
pnpm test


# Tests específicos
pnpm test -- --grep "TextUtils"


# Tests con coverage
pnpm test:coverage


# Tests en modo watch
pnpm test:watch

🔀 Flujo de Trabajo Git

Ramas

Ventana de terminal
main                 # Rama principal (producción)
├── develop         # Rama de desarrollo
├── feature/nombre  # Nuevas funcionalidades
├── bugfix/nombre   # Correcciones de bugs
├── hotfix/nombre   # Correcciones urgentes
└── release/vX.X.X  # Preparación de releases

Comandos Git

Ventana de terminal
# Crear rama de feature
git checkout develop
git pull origin develop
git checkout -b feature/nueva-funcionalidad


# Commit con mensaje descriptivo
git add .
git commit -m "feat: agregar comando de ejemplo


- Implementar comando slash /ejemplo
- Agregar traducciones es/en
- Incluir tests unitarios
- Actualizar documentación


Fixes #123"


# Push y crear PR
git push origin feature/nueva-funcionalidad
# Crear Pull Request en GitHub

Convención de Commits

Ventana de terminal
# Tipos de commit
feat:     # Nueva funcionalidad
fix:      # Corrección de bug
docs:     # Cambios en documentación
style:    # Cambios de formato (no afectan lógica)
refactor: # Refactorización de código
test:     # Agregar o modificar tests
chore:    # Tareas de mantenimiento


# Ejemplos
git commit -m "feat: agregar sistema de roles automáticos"
git commit -m "fix: corregir error en cálculo de XP"
git commit -m "docs: actualizar guía de instalación"
git commit -m "refactor: mejorar manejo de errores en tickets"

📋 Pull Request Guidelines

Checklist antes de crear PR

  • ✅ Código sigue las convenciones establecidas
  • ✅ Tests pasan correctamente
  • ✅ Documentación actualizada
  • ✅ Traducciones incluidas (es/en)
  • ✅ No hay conflictos de merge
  • ✅ Commits están bien estructurados
  • ✅ PR tiene descripción clara

Template de Pull Request

## 📝 Descripción
Descripción clara y concisa de los cambios realizados.


## 🎯 Tipo de Cambio
- [ ] 🐛 Bug fix
- [ ] ✨ Nueva funcionalidad
- [ ] 💥 Breaking change
- [ ] 📚 Documentación
- [ ] 🔧 Refactorización


## 🧪 Testing
- [ ] Tests unitarios pasando
- [ ] Tests de integración pasando
- [ ] Probado manualmente en servidor de desarrollo


## 📸 Screenshots
(Si aplica, incluir capturas de pantalla)


## 📝 Checklist
- [ ] Código sigue las convenciones del proyecto
- [ ] Self-review realizado
- [ ] Documentación actualizada
- [ ] Traducciones incluidas
- [ ] Tests agregados/actualizados


## 🔗 Issues Relacionados
Fixes #123
Closes #456
Related to #789

🐛 Reportar Issues

Template de Bug Report

## 🐛 Descripción del Bug
Descripción clara y concisa del problema.


## 🔄 Pasos para Reproducir
1. Ir a '...'
2. Ejecutar comando '...'
3. Ver error


## ✅ Comportamiento Esperado
Descripción de lo que debería pasar.


## 🔥 Comportamiento Actual
Descripción de lo que está pasando.


## 🖼️ Screenshots
(Si aplica)


## 🌍 Entorno
- OS: [ej. Windows 10]
- Node.js: [ej. v18.17.0]
- Bot version: [ej. v1.2.3]
- Discord.js: [ej. v14.14.1]


## 📋 Logs

Incluir logs relevantes aquí

## 📊 Información Adicional
Cualquier otra información que pueda ser útil.

Template de Feature Request

## 💡 Descripción de la Funcionalidad
Descripción clara y concisa de la funcionalidad propuesta.


## 🎯 Problema que Resuelve
¿Qué problema resuelve esta funcionalidad?


## 💭 Solución Propuesta
Descripción de la solución que te gustaría ver.


## 🔀 Alternativas Consideradas
Otras soluciones o funcionalidades que has considerado.


## 🖼️ Mockups/Ejemplos
(Si aplica, incluir ejemplos visuales)


## 📊 Contexto Adicional
Cualquier otra información relevante.

🏷️ Labels en GitHub

Tipos de Issues

  • bug - Error en el código
  • enhancement - Nueva funcionalidad
  • documentation - Mejoras en docs
  • translation - Temas de traducciones
  • question - Preguntas generales

Prioridad

  • priority: high - Alta prioridad
  • priority: medium - Prioridad media
  • priority: low - Baja prioridad

Estado

  • status: ready - Listo para trabajar
  • status: in-progress - En desarrollo
  • status: needs-review - Necesita revisión
  • status: blocked - Bloqueado

Áreas

  • area: commands - Comandos del bot
  • area: database - Base de datos
  • area: docs - Documentación
  • area: i18n - Internacionalización

🎉 Reconocimientos

Contributors

Todos los contribuidores son reconocidos en:

  • README.md principal
  • Página de créditos en documentación
  • Releases notes

Tipos de Contribución

  • 💻 Código
  • 📖 Documentación
  • 🐛 Bug reports
  • 💡 Ideas
  • 🌍 Traducciones
  • 🎨 Diseño
  • 🧪 Testing

📞 Contacto y Soporte

Canales de Comunicación

  • GitHub Issues - Bugs y features
  • GitHub Discussions - Preguntas generales
  • Discord Server - Chat en tiempo real
  • Email - Contacto directo con maintainers

Maintainers

  • @tu-usuario - Lead Developer
  • Lista de maintainers activos

📜 Código de Conducta

Nuestro Compromiso

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

Comportamientos Esperados

  • Usar lenguaje respetuoso e inclusivo
  • Respetar diferentes puntos de vista
  • Aceptar críticas constructivas gracefully
  • Enfocarse en lo mejor para la comunidad

Comportamientos Inaceptables

  • Uso de lenguaje o imágenes sexualizadas
  • Trolling, comentarios insultantes
  • Acoso público o privado
  • Publicar información privada sin permiso

Aplicación

Los maintainers tienen el derecho y la responsabilidad de remover, editar o rechazar contribuciones que no se alineen con este Código de Conducta.

¡Gracias por contribuir a DiscordBot-TK! Cada contribución, por pequeña que sea, hace que el proyecto sea mejor para todos. 🚀