Contribuindo para o desenvolvimento do Discourse

[Discourse]

Este guia foi elaborado para aqueles que desejam contribuir para o projeto open-source Discourse, detalhando a configuração e as convenções necessárias para uma colaboração eficaz.

Nível de usuário exigido: Embora qualquer um possa contribuir com código, você precisará estar familiarizado com Ruby e JavaScript.

Sumário

Esta documentação cobrirá o seguinte:

• Configurando seu ambiente de desenvolvimento
• Entendendo por onde começar a contribuir
• Criando e trabalhando com plugins do Discourse
• Contribuindo para o core do Discourse
• Convenções de codificação a serem seguidas
• Enviando suas contribuições no GitHub

Configurando o ambiente de desenvolvimento

Antes de começar a contribuir, certifique-se de que seu ambiente de desenvolvimento esteja configurado corretamente. Siga o guia apropriado para sua plataforma:

• Todas as plataformas: Install Discourse for Development using Docker
• Mac OS X: Beginner’s Guide to Install Discourse on macOS for Development
• Linux (Ubuntu): Beginner’s Guide to Install Discourse on Ubuntu for Development
• Windows: Beginner’s Guide to Install Discourse on Windows 10 for Development

Sabendo por onde começar

Discourse é um projeto grande, e entender suas tecnologias subjacentes, como Ruby e JavaScript, é essencial. Para orientação sobre como começar, consulte o guia para novatos.

Criando e trabalhando com plugins

Plugins oferecem uma maneira de entender os detalhes internos do Discourse em porções gerenciáveis e permitem que você comece a contribuir com código facilmente. Comece com:

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

Para inspiração, explore ideias populares em #feature e #plugin:extras.

Contribuindo para o core do Discourse

O código principal do Discourse é gerenciado no repositório principal no GitHub.

Assinando o CLA

Antes de contribuir, leia e assine o Electronic Discourse Forums Contribution License Agreement. A equipe não pode aceitar legalmente pull requests (PRs) de usuários que não assinaram o CLA.

Aquecendo com tarefas de iniciante

Explore a tag pr-welcome para boas tarefas para começar.

Trabalhando na lista de bugs

Corrija bugs da lista de bugs abertos ordenados por curtidas. Deixe uma nota se você estiver trabalhando em um bug — se não o concluir, deixe quaisquer notas relevantes para que outra pessoa continue seu trabalho.

Ajudando com tópicos de recursos (features)

Contribua com detalhes e mockups para solicitações de recursos para auxiliar no processo de aprovação. Lembre-se, nem todo recurso será incluído no core.

Melhorando o desempenho

Aceitamos pull requests que aprimorem o desempenho do lado do cliente ou do servidor, focando em áreas de alto impacto, como o carregamento inicial da página inicial ou da visualização de tópicos.

Melhorando projetos mantidos pelo Discourse

Contribua para outros projetos open-source mantidos pelo Discourse. Alguns projetos notáveis incluem:

• Logster - visualizador de logs GUI web
• Message Bus - motor para interações de site ao vivo
• Rack Mini Profiler - ferramenta de diagnóstico
• Discourse API - consumidor de API
• Discourse Docker - motor de distribuição do Discourse
• WP Discourse - plugin para WordPress
• Memory Profiler - profiler para Ruby
• Ember Performance - suíte de testes de desempenho do Ember

Convenções de codificação

A Nomenclatura é CRUCIAL

Busque 100% de paridade entre os termos usados no site e os nomes de classes e colunas no banco de dados (ex: “posts”).

A Compatibilidade com as versões mais recentes das dependências é CRUCIAL

Garanta a compatibilidade com as versões estáveis mais recentes de bibliotecas como Rails, Ruby e Ember. Teste regressões ao atualizar dependências.

Contribuições apenas de teste são bem-vindas

Contribuições de teste são bem-vindas, especialmente para processos e ações de controlador não testados. Evite mocking a menos que seja absolutamente necessário.

Contribuições apenas de refatoração NÃO são bem-vindas

Evite enviar pull requests contendo apenas refatoração. Em vez disso, corrija um bug ou implemente um recurso enquanto melhora o código.

Enviando código no GitHub

Fluxo de trabalho passo a passo

1. Clonar o repositório Discourse:

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

2. Criar um novo branch:

   cd discourse
   git checkout -b new_discourse_branch
   

3. Codificar:

   • Cumpra as convenções de código existentes que você encontra no código.
   • Inclua testes e garanta que eles passem.
   • Faça referência a discussões relevantes no fórum meta do Discourse.

4. Seguir as convenções de codificação:

   • duasS espaços, sem tabulações
   • sem espaços em branco finais, linhas em branco não devem ter espaços
   • use espaços ao redor de operadores, após vírgulas, dois-pontos, ponto e vírgula, ao redor de { e antes de }
   • sem espaço após (, [ ou antes de ], )
   • use a sintaxe de hash do Ruby 1.9: prefira { a: 1 } a { :a => 1 }
   • prefira class << self; def method; end a def self.method para métodos de classe
   • prefira { ... } a do ... end para blocos de linha única, evite usar { ... } para blocos de múltiplas linhas
   • evite return quando não for necessário

5. Commitar:

   git commit -m "Um breve resumo da mudança" -m "Uma descrição detalhada da mudança"
   

   Nunca deixe uma mensagem de commit em branco — este é um guia útil para escrever mensagens de commit. A mensagem deve começar com um breve resumo (máx. 72 caracteres) na primeira linha, seguido por uma linha em branco, e depois uma descrição mais detalhada da mudança. Você pode usar sintaxe markdown para estilo simples, se necessário.

   Certifique-se de prefixar os títulos dos commits de acordo com as convenções do Discourse.

   5 (a). Linting:
   O código JavaScript é verificado com eslint e formatado com prettier. Ruby é verificado com RuboCop e formatado com Syntax Tree. SCSS/CSS é verificado com stylelint. Templates Ember são verificados com ember-template-lint. Todas essas verificações são executadas automaticamente nas ações do GitHub sempre que você cria um pull request para o Discourse.

   • É altamente recomendável que você instale nossos hooks de pre-commit do git usando lefthook. Isso será executado automaticamente toda vez que você fizer um commit no core do Discourse, e levantará problemas com as várias linguagens e templates antes que você os envie e precise esperar o CI do GitHub ser executado. Execute isto no diretório raiz do seu projeto:

     pnpm lefthook install
     

6. Atualizar seu branch:

   git fetch origin
   git rebase origin/main
   

7. Fork:

   git remote add mine git@github.com:<seu-nome-de-usuário>/discourse.git
   

8. Enviar (push) para seu remote:

   git push mine new_discourse_branch
   

9. Emitir um pull request:

   • Navegue até seu repositório no GitHub.
   • Clique em “Pull Request”.
   • Digite o nome do seu branch no campo de branch.
   • Clique em “Update Commit Range”.
   • Verifique as alterações nas abas “Commits” e “Files Changed”.
   • Forneça um título e descrição.
   • Clique em “Send pull request”.

   Antes de enviar um pull-request, limpe o histórico, revise seus commits e agrupe (squash) pequenas alterações e correções nos commits correspondentes. Você pode agrupar commits com o comando de rebase interativo:

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

# o editor abre e permite que você altere o histórico de commits 
# siga as instruções na parte inferior do editor

git push -f mine new_discourse_branch

10. Responder ao feedback:
    • Seja receptivo ao feedback e esteja pronto para implementar as alterações sugeridas.
    • Lembre-se, feedback significa que seu trabalho é valorizado e destinado à inclusão.

Obrigado por contribuir para o projeto open-source Discourse!