Esta guía está diseñada para aquellos que deseen contribuir al proyecto de código abierto de Discourse, detallando la configuración y las convenciones necesarias para una colaboración efectiva.
Nivel de usuario requerido: Si bien cualquiera puede contribuir con código, deberá estar familiarizado con Ruby y JavaScript.
Resumen
Esta documentación cubrirá lo siguiente:
- Configuración de su entorno de desarrollo
- Comprensión de por dónde empezar a contribuir
- Creación y trabajo con plugins de Discourse
- Contribución al núcleo de Discourse
- Convenciones de codificación a seguir
- Envío de sus contribuciones en GitHub
Configuración del entorno de desarrollo
Antes de comenzar a contribuir, asegúrese de que su entorno de desarrollo esté configurado correctamente. Siga la guía apropiada para su plataforma:
- Todas las plataformas: Instalar Discourse para desarrollo usando Docker
- Mac OS X: Guía para principiantes para instalar Discourse en macOS para desarrollo
- Linux (Ubuntu): Guía para principiantes para instalar Discourse en Ubuntu para desarrollo
- Windows: Guía para principiantes para 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 empezar, consulte la guía para novatos.
Creación y trabajo con plugins
Los plugins ofrecen una forma de comprender los internos de Discourse en porciones manejables y le permiten comenzar a contribuir con código fácilmente. Comience con:
- Developing Discourse Plugins - Part 1 - Create a basic plugin
- (deprecated) Plugin outlet locations theme component
Para inspiración, explore ideas populares en Feature y Plugin > Extras.
Contribución al núcleo de Discourse
El código central de Discourse se gestiona en el repositorio central en GitHub.
Firma del CLA
Antes de contribuir, lea y firme el Acuerdo de Licencia de Contribución de Foros Electrónicos de Discourse. El equipo no puede aceptar legalmente solicitudes de extracción (PRs) de usuarios que no hayan firmado el CLA.
Calentamiento con tareas iniciales
Explore la etiqueta pr-welcome para buenas tareas para comenzar.
Trabajar a través de la lista de errores (bugs)
Arregle errores de la lista de errores abiertos ordenados por “me gusta”. Deje una nota si está trabajando en un error; si no lo completa, deje cualquier nota relevante para que otra persona continúe su trabajo.
Ayuda con temas de características (features)
Contribuya con detalles y maquetas a las solicitudes de características para ayudar en su proceso de aprobación. Recuerde, no todas las características se incluirán en el núcleo.
Mejorar el rendimiento
Agradecemos las solicitudes de extracción que mejoren el rendimiento del lado del cliente o del servidor, centrándose 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
Contribuya a otros proyectos de código abierto mantenidos por Discourse. Algunos proyectos notables incluyen:
- Logster - visor de registros GUI web
- Message Bus - motor para interacciones de sitios en vivo
- Rack Mini Profiler - herramienta de diagnóstico
- Onebox - gema Ruby para previsualizaciones de URL
- Discourse API - consumidor de API
- Discourse Docker - motor de distribución de Discourse
- WP Discourse - plugin de WordPress
- Memory Profiler - perfilador para Ruby
- Ember Performance - conjunto de pruebas de rendimiento de Ember
Convenciones de codificación
El nombramiento es CRÍTICO
Busque 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 (ej. “posts”).
La compatibilidad con las últimas versiones de las dependencias es CRÍTICA
Asegure la compatibilidad con las últimas versiones estables de librerías como Rails, Ruby y Ember. Pruebe si hay regresiones al actualizar dependencias.
Las contribuciones solo de pruebas son bienvenidas
Se agradecen las contribuciones de pruebas, especialmente para procesos y acciones de controlador no probados. Evite simular (mocking) a menos que sea absolutamente necesario.
Las contribuciones solo de refactorización NO son bienvenidas
Evite enviar solicitudes de extracción que solo sean de refactorización. En su lugar, arregle un error o implemente una característica mientras mejora el código.
Envío de código en GitHub
Flujo de trabajo paso a paso
-
Clonar el repositorio de Discourse:
git clone git@github.com:discourse/discourse.git -
Crear una nueva rama:
cd discourse git checkout -b nueva_rama_discourse -
Codificar:
- Adhiérase a las convenciones de código existentes que encuentre en el código.
- Incluya pruebas y asegúrese de que pasen.
- Haga referencia a discusiones relevantes en el foro meta de Discourse.
-
Seguir las convenciones de codificación:
- dos espacios, sin tabulaciones
- sin espacios en blanco al final, las líneas en blanco no deben tener espacios
- use espacios alrededor de operadores, después de comas, dos puntos, punto y coma, alrededor de
{y antes de} - sin espacio después de
(,[o antes de],) - use la sintaxis de hash de Ruby 1.9: prefiera
{ a: 1 }sobre{ :a => 1 } - prefiera
class << self; def method; endsobredef self.methodpara métodos de clase - prefiera
{ ... }sobredo ... endpara bloques de una sola línea, evite usar{ ... }para bloques de varias líneas - evite
returncuando no sea necesario
-
Confirmar (Commit):
git commit -m "Un breve resumen del cambio" -m "Una descripción detallada del cambio"Nunca deje un 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 breve (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. Puede usar sintaxis markdown para un estilo simple si es necesario.
Asegúrese de prefijar los títulos de confirmación de acuerdo con las convenciones de Discourse.
5 (a). Análisis de código (Linting):
El código JavaScript se analiza con eslint y las condiciones de formato de prettier. Ruby se analiza con RuboCop. Todas estas comprobaciones se ejecutan automáticamente en las acciones de GitHub cada vez que crea una solicitud de extracción para Discourse.- Es muy recomendable que instale nuestros ganchos (hooks) de git previos a la confirmación usando
lefthook. Esto se ejecutará automáticamente cada vez que realice una confirmación en el núcleo de Discourse, y planteará problemas con los diversos lenguajes y plantillas antes de enviarlos y tener que esperar a que se ejecute CI de GitHub. Ejecute esto en la raíz de su proyecto:mkdir .git/hooks npx lefthook install
- Es muy recomendable que instale nuestros ganchos (hooks) de git previos a la confirmación usando
-
Actualizar su rama:
git fetch origin git rebase origin/main -
Bifurcar (Fork):
git remote add mine git@github.com:<your-username>/discourse.git -
Enviar a su remoto:
git push mine nueva_rama_discourse -
Emitir una solicitud de extracción:
- Navegue a su repositorio en GitHub.
- Haga clic en “Pull Request”.
- Escriba el nombre de su rama en el campo de la rama.
- Haga clic en “Update Commit Range”.
- Verifique los cambios en las pestañas “Commits” y “Files Changed”.
- Proporcione un título y una descripción.
- Haga clic en “Send pull request”.
Antes de enviar una solicitud de extracción, limpie el historial, revise sus confirmaciones y fusione (squash) cambios menores y correcciones en las confirmaciones correspondientes. Puede fusionar confirmaciones con el comando de rebase interactivo:
git fetch origin
git checkout nueva_rama_discourse
git rebase origin/main
git rebase -i
< se abre el editor y le permite cambiar el historial de confirmación >
< siga las instrucciones en la parte inferior del editor >
git push -f mine nueva_rama_discourse
- Responder a los comentarios:
- Sea receptivo a los comentarios y esté listo para implementar los cambios sugeridos.
- Recuerde, los comentarios significan que su trabajo es valorado y está destinado a ser incluido.
¡Gracias por contribuir al proyecto de código abierto de Discourse!
