Esta guía está diseñada para quienes deseen 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, debes estar familiarizado con Ruby y JavaScript.
Resumen
Esta documentación cubrirá lo siguiente:
- Configuración de tu entorno de desarrollo
- Cómo 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 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 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, consulta la guía para nuevos.
Creación y trabajo con plugins
Los plugins ofrecen una manera de entender los componentes internos de Discourse en partes manejables y te permiten comenzar a contribuir con código fácilmente. Empieza con:
- Developing Discourse Plugins - Part 1 - Create a basic plugin
- (deprecated) Plugin outlet locations theme component
Para obtener inspiración, explora ideas populares en Contribute > Feature y Customization > 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 Electrónica de Discourse Forums. El equipo no puede aceptar legalmente solicitudes de extracción (PR) de usuarios que no hayan firmado el CLA.
Calentamiento con tareas iniciales
Explora la etiqueta pr-welcome para encontrar buenas tareas con las que empezar.
Trabaja con la lista de errores
Corrige errores de la lista de errores abiertos ordenados por likes. Deja una nota si estás trabajando en un error; si no lo completas, deja cualquier nota relevante para que otra persona continúe tu trabajo.
Ayuda con temas de características
Contribuye con detalles y maquetas a las solicitudes de características para ayudar en su proceso de aprobación. Recuerda, no todas las características se incluirán en el núcleo.
Mejora del 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.
Mejora de 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 gráfica web
- Message Bus - motor para interacciones en vivo del sitio
- Rack Mini Profiler - herramienta de diagnóstico
- 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 - suite de pruebas de rendimiento para Ember
Convenciones de codificación
La nomenclatura es CRÍTICA
Busca 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 versiones más recientes de las dependencias es CRÍTICA
Asegura la compatibilidad con las versiones estables más recientes de bibliotecas como Rails, Ruby y Ember. Prueba en busca de regresiones al actualizar dependencias.
Las contribuciones solo de pruebas son bienvenidas
Se agradecen las contribuciones de pruebas, especialmente para procesos y acciones de controladores no probados. Evita la simulación (mocking) a menos que sea absolutamente necesario.
Las contribuciones solo de refactorización NO son bienvenidas
Evita enviar solicitudes de extracción que solo realicen refactorizaciones. 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
-
Clona el repositorio de Discourse:
git clone https://github.com/discourse/discourse.git -
Crea una nueva rama:
cd discourse git checkout -b new_discourse_branch -
Codifica:
- Adhiérete a las convenciones de código existentes que encuentres en el código.
- Incluye pruebas y asegúrate de que pasen.
- Haz referencia a discusiones relevantes en el foro meta de Discourse.
-
Sigue las convenciones de codificación:
- dos espacios, sin tabuladores
- sin espacios en blanco al final, las líneas en blanco no deben tener espacios
- usa espacios alrededor de operadores, después de comas, dos puntos, puntos y coma, alrededor de
{y antes de} - sin espacio después de
(,[ni antes de],) - usa la sintaxis de hash de Ruby 1.9: prefiere
{ a: 1 }sobre{ :a => 1 } - prefiere
class << self; def method; endsobredef self.methodpara métodos de clase - prefiere
{ ... }sobredo ... endpara bloques de una sola línea; evita usar{ ... }para bloques de varias líneas - evita
returncuando no sea necesario
-
Commitea:
git commit -m «Un resumen breve del cambio» -m «Una descripción detallada del cambio»Nunca dejes un mensaje de commit en blanco; esta es una guía útil para escribir mensajes de commit. 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. Puedes usar sintaxis de markdown para un estilo simple si es necesario.
Asegúrate de prefijar los títulos de los commits según las convenciones de Discourse.
5 (a). Linting:
El código JavaScript se revisa con eslint y se formatea con prettier. Ruby se revisa con RuboCop y se formatea con Syntax Tree. SCSS/CSS se revisa con stylelint. Las plantillas de Ember se revisan con ember-template-lint. Todos estos controles 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 hooks de git pre-commit usando
lefthook. Esto se ejecutará automáticamente cada vez que hagas un commit en el núcleo de Discourse y señalará problemas con los diversos lenguajes y plantillas antes de subirlos y tener que esperar a que GitHub CI se ejecute. Ejecuta esto en la raíz de tu proyecto:pnpm lefthook install
- Se recomienda encarecidamente que instales nuestros hooks de git pre-commit usando
-
Actualiza tu rama:
git fetch origin git rebase origin/main -
Haz un fork:
git remote add mine git@github.com:<tu-usuario>/discourse.git -
Sube a tu remoto:
git push mine new_discourse_branch -
Presenta una solicitud de extracción:
- Navega a tu repositorio en GitHub.
- Haz clic en «Pull Request».
- Escribe el nombre de tu rama en el campo de rama.
- Haz clic en «Update Commit Range».
- Verifica los cambios en las pestañas «Commits» y «Files Changed».
- Proporciona un título y una descripción.
- Haz clic en «Send pull request».
Antes de enviar una solicitud de extracción, limpia el historial, revisa tus commits y fusiona (squash) los cambios menores y las correcciones en los commits correspondientes. Puedes fusionar commits con el comando de rebase interactivo:
git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i
< el editor se abre y te permite cambiar el historial de commits >
< sigue las instrucciones en la parte inferior del editor >
git push -f mine new_discourse_branch
- Responde a los comentarios:
- Sé receptivo a los comentarios y listo para implementar los cambios sugeridos.
- Recuerda, los comentarios significan que tu trabajo es valorado y está destinado a ser incluido.
¡Gracias por contribuir al proyecto de código abierto Discourse!