Contribuir al desarrollo de Discourse

[Discourse]

Esta guía está diseñada para quienes desean contribuir al proyecto de código abierto Discourse, detallando la configuración y las convenciones necesarias para una colaboración efectiva.

Nivel de usuario requerido: Aunque cualquiera puede contribuir con código, es necesario tener conocimientos de Ruby y JavaScript.

Resumen

Esta documentación cubrirá los siguientes puntos:

• Configuración de tu entorno de desarrollo
• Comprensión de por dónde empezar a contribuir
• Creación y uso de complementos (plugins) de Discourse
• Contribución al núcleo (core) de Discourse
• Convenciones de codificación a seguir
• Envío de tus contribuciones en GitHub

Configuración del entorno de desarrollo

Antes de comenzar a contribuir, asegúrate de que tu entorno de desarrollo esté configurado correctamente. Sigue la guía adecuada para tu plataforma:

• Todas las plataformas: Instalar Discourse para desarrollo usando Docker
• Mac OS X: Guía para principiantes: Instalar Discourse en macOS para desarrollo
• Linux (Ubuntu): Guía para principiantes: Instalar Discourse en Ubuntu para desarrollo
• Windows: Guía para principiantes: Instalar Discourse en Windows 10 para desarrollo

Saber por dónde empezar

Discourse es un proyecto grande, y comprender sus tecnologías subyacentes, como Ruby y JavaScript, es esencial. Para obtener orientación sobre cómo comenzar, consulta la guía para principiantes.

Creación y uso de complementos

Los complementos ofrecen una forma de entender los componentes internos de Discourse en partes manejables y te permiten comenzar a contribuir código fácilmente. Comienza con:

• Developing Discourse Plugins - Part 1 - Create a basic plugin
• (deprecated) Plugin outlet locations theme component

Para inspirarte, explora las ideas populares en Contribute > Feature y #plugin:extras.

Contribución al núcleo de Discourse

El código del núcleo de Discourse se gestiona en el repositorio principal en GitHub.

Firmar el CLA

Antes de contribuir, lee y firma el Acuerdo de Licencia de Contribución de los Foros Electrónicos Discourse. El equipo no puede aceptar legalmente solicitudes de extracción (PR) de usuarios que no hayan firmado el CLA.

Calentar con tareas iniciales

Explora la etiqueta pr-welcome para encontrar buenas tareas para comenzar.

Trabajar con la lista de errores

Corrige errores de la lista de errores abiertos ordenados por me gusta. Deja una nota si estás trabajando en un error; si no lo completas, deja cualquier nota relevante para que otra persona pueda continuar con tu trabajo.

Ayudar con temas de características

Contribuye con detalles y maquetas (mockups) a las solicitudes de características para ayudar en su proceso de aprobación. Recuerda que no todas las características se incluirán en el núcleo.

Mejorar el rendimiento

Damos la bienvenida a solicitudes de extracción que mejoren el rendimiento del lado del cliente o del servidor, centrándonos en áreas de alto impacto como la carga inicial de la página principal o la vista de temas.

Mejorar los proyectos mantenidos por Discourse

Contribuye a otros proyectos de código abierto mantenidos por Discourse. Algunos proyectos destacados incluyen:

• Logster - visor de registros con interfaz web
• Message Bus - motor para interacciones en tiempo real en el sitio
• Rack Mini Profiler - herramienta de diagnóstico
• Discourse API - consumidor de API
• Discourse Docker - motor de distribución de Discourse
• WP Discourse - complemento para WordPress
• Memory Profiler - profiler para Ruby
• Ember Performance - suite de pruebas de rendimiento para Ember

Convenciones de codificación

El nombre es CRÍTICO

Apunta a una paridad del 100% entre los términos utilizados en el sitio y los nombres de las clases y columnas en la base de datos (por ejemplo, “posts”).

La compatibilidad con las últimas versiones de las dependencias es CRÍTICA

Asegúrate de la compatibilidad con las últimas versiones estables de bibliotecas como Rails, Ruby y Ember. Prueba la aparición de regresiones al actualizar las dependencias.

Las contribuciones solo de pruebas son bienvenidas

Se aceptan contribuciones de pruebas, especialmente para procesos y acciones de controladores no probados. Evita el uso de simulacros (mocking) a menos que sea absolutamente necesario.

Las contribuciones solo de refactorización NO son bienvenidas

Evita enviar solicitudes de extracción que sean solo de refactorización. En su lugar, corrige un error o implementa una característica mientras mejoras el código.

Envío de código en GitHub

Flujo de trabajo paso a paso

1. Clonar el repositorio de Discourse:

   git clone https://github.com/discourse/discourse.git
   

2. Crear una nueva rama:

   cd discourse
   git checkout -b new_discourse_branch
   

3. Codificar:

   • Adhiérete a las convenciones de código existentes que encuentres en el código.
   • Incluye pruebas y asegúrate de que pasen.
   • Referencia discusiones relevantes en el foro meta de Discourse.

4. Seguir las convenciones de codificación:

   • dos espacios, sin tabulaciones
   • sin espacios en blanco al final de las líneas; las líneas en blanco no deben tener espacios
   • usar espacios alrededor de los operadores, después de comas, dos puntos, puntos y comas, alrededor de { y antes de }
   • sin espacio después de (, [ o antes de ], )
   • usar la sintaxis de hash de Ruby 1.9: preferir { a: 1 } sobre { :a => 1 }
   • preferir class << self; def method; end sobre def self.method para métodos de clase
   • preferir { ... } sobre do ... end para bloques de una sola línea; evitar usar { ... } para bloques de múltiples líneas
   • evitar return cuando no es necesario

5. Confirmar (Commit):

   git commit -m "Un resumen corto del cambio" -m "Una descripción detallada del cambio"
   

   Nunca dejes el mensaje de confirmación en blanco; esta es una guía útil para escribir mensajes de confirmación. El mensaje debe comenzar con un resumen corto (máximo 72 caracteres) en la primera línea, seguido de una línea en blanco y luego una descripción más detallada del cambio. Puedes usar la sintaxis de markdown para un estilo simple si es necesario.

   Asegúrate de prefijar los títulos de las confirmaciones según las convenciones de Discourse.

   5 (a). Análisis estático (Linting):
   El código JavaScript se analiza con eslint y se formatea con prettier. Ruby se analiza con RuboCop y se formatea con Syntax Tree. SCSS/CSS se analiza con stylelint. Las plantillas de Ember se analizan con ember-template-lint. Todas estas comprobaciones se ejecutan automáticamente en las acciones de GitHub cada vez que creas una solicitud de extracción para Discourse.

   • Se recomienda encarecidamente que instales nuestros ganchos de git pre-commit usando lefthook. Esto se ejecutará automáticamente cada vez que hagas una confirmación en el núcleo de Discourse y señalará problemas con los diversos lenguajes y plantillas antes de que los subas y tengas que esperar a que se ejecuten las CI de GitHub. Ejecuta esto en la raíz de tu proyecto:

     pnpm lefthook install
     

6. Actualizar tu rama:

   git fetch origin
   git rebase origin/main
   

7. Crear un fork:

   git remote add mine git@github.com:<your-username>/discourse.git
   

8. Subir a tu remoto:

   git push mine new_discourse_branch
   

9. Enviar una solicitud de extracción:

   • Navega a tu repositorio en GitHub.
   • Haz clic en “Pull Request” (Solicitud de extracción).
   • Escribe el nombre de tu rama en el campo de rama.
   • Haz clic en “Update Commit Range” (Actualizar rango de confirmaciones).
   • Verifica los cambios en las pestañas “Commits” (Confirmaciones) y “Files Changed” (Archivos modificados).
   • Proporciona un título y una descripción.
   • Haz clic en “Send pull request” (Enviar solicitud de extracción).

   Antes de enviar una solicitud de extracción, limpia el historial, revisa tus confirmaciones y combina los cambios menores y correcciones en las confirmaciones correspondientes. Puedes combinar confirmaciones con el comando de rebase interactivo:

git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i

< se abre el editor y te permite cambiar el historial de confirmaciones >
< sigue las instrucciones en la parte inferior del editor >

git push -f mine new_discourse_branch

10. Responder a los comentarios:
    • Sé receptivo a los comentarios y está preparado para implementar los cambios sugeridos.
    • Recuerda que los comentarios significan que tu trabajo es valorado y está destinado a ser incluido.

¡Gracias por contribuir al proyecto de código abierto Discourse!