Este guia foi elaborado para aqueles que desejam contribuir com o projeto de código aberto Discourse, detalhando a configuração e as convenções necessárias para uma colaboração eficaz.
Nível de usuário necessário: Embora qualquer pessoa possa contribuir com código, você precisa estar familiarizado com Ruby e JavaScript.
Resumo
Esta documentação abordará os seguintes tópicos:
- Configuração do seu ambiente de desenvolvimento
- Compreensão de onde começar a contribuir
- Criação e uso de plugins do Discourse
- Contribuição para o núcleo do Discourse
- Convenções de codificação a seguir
- Envio de 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: Instale o Discourse para Desenvolvimento usando Docker
- Mac OS X: Guia para Iniciantes: Instale o Discourse no macOS para Desenvolvimento
- Linux (Ubuntu): Guia para Iniciantes: Instale o Discourse no Ubuntu para Desenvolvimento
- Windows: Guia para Iniciantes: Instale o Discourse no Windows 10 para Desenvolvimento
Sabendo por onde começar
O Discourse é um projeto grande, e compreender suas tecnologias subjacentes, como Ruby e JavaScript, é essencial. Para orientações sobre como começar, consulte o guia para iniciantes.
Criando e trabalhando com plugins
Os plugins oferecem uma maneira de entender os internals do Discourse em partes 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 Contribute > Feature e Customization > Extras.
Contribuindo para o núcleo do Discourse
O código do núcleo do Discourse é gerenciado no repositório principal no GitHub.
Assinatura do CLA
Antes de contribuir, leia e assine o Acordo de Licença de Contribuição dos Fóruns Eletrônicos Discourse. A equipe não pode aceitar legalmente pull requests (PRs) de usuários que não tenham assinado o CLA.
Aquecendo com tarefas iniciais
Explore a tag pr-welcome para boas tarefas para começar.
Trabalhando na lista de bugs
Corrija bugs na lista de bugs abertos ordenados por curtidas. Deixe uma nota se estiver trabalhando em um bug; se não o concluir, deixe quaisquer notas relevantes para que outra pessoa possa continuar seu trabalho.
Ajuda com tópicos de recursos
Contribua com detalhes e mockups para solicitações de recursos para auxiliar no processo de aprovação. Lembre-se de que nem todo recurso será incluído no núcleo.
Melhorar o desempenho
Aceitamos pull requests que melhorem 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.
Melhorar projetos mantidos pelo Discourse
Contribua para outros projetos de código aberto mantidos pelo Discourse. Alguns projetos notáveis incluem:
- Logster - visualizador de logs GUI web
- Message Bus - mecanismo para interações em tempo real no site
- Rack Mini Profiler - ferramenta de diagnóstico
- Discourse API - consumidor de API
- Discourse Docker - mecanismo 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
Nomenclatura é CRÍTICA
Busque 100% de paridade entre os termos usados no site e os nomes das classes e colunas no banco de dados (por exemplo, “posts”).
Compatibilidade com as versões mais recentes das dependências é CRÍTICA
Garanta a compatibilidade com as versões estáveis mais recentes de bibliotecas como Rails, Ruby e Ember. Teste a ocorrência de regressões ao atualizar as dependências.
Contribuições apenas de testes são bem-vindas
Contribuições de testes são bem-vindas, especialmente para processos e ações de controladores não testados. Evite mocks, a menos que seja absolutamente necessário.
Contribuições apenas de refatoração NÃO são bem-vindas
Evite enviar pull requests que sejam apenas de 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
-
Clone o repositório do Discourse:
git clone https://github.com/discourse/discourse.git -
Crie um novo branch:
cd discourse git checkout -b new_discourse_branch -
Codifique:
- Adira às convenções de código existentes que você encontrar no código.
- Inclua testes e certifique-se de que passem.
- Referencie discussões relevantes no fórum meta do Discourse.
-
Siga as convenções de codificação:
- dois espaços, sem tabs
- sem espaços em branco à direita; 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} - não use 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; endadef self.methodpara métodos de classe - prefira
{ ... }ado ... endpara blocos de uma única linha; evite usar{ ... }para blocos de várias linhas - evite
returnquando não for necessário
-
Commit:
git commit -m "Um resumo curto da alteração" -m "Uma descrição detalhada da alteração"Nunca deixe a mensagem do commit em branco - este é um guia útil para escrever mensagens de commit. A mensagem deve começar com um resumo curto (máximo de 72 caracteres) na primeira linha, seguido por uma linha em branco e, em seguida, uma descrição mais detalhada da alteração. Você pode usar a sintaxe de markdown para estilização 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. O Ruby é verificado com RuboCop e formatado com Syntax Tree. O SCSS/CSS é verificado com stylelint. Os templates do 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.- É fortemente recomendável que você instale nossos hooks git pré-commit usando
lefthook. Isso será executado automaticamente toda vez que você fizer um commit no núcleo do Discourse e sinalizará problemas com as várias linguagens e templates antes de você enviá-los e ter que esperar que o CI do GitHub seja executado. Execute isso na raiz do seu projeto:pnpm lefthook install
- É fortemente recomendável que você instale nossos hooks git pré-commit usando
-
Atualize seu branch:
git fetch origin git rebase origin/main -
Fork:
git remote add mine git@github.com:<your-username>/discourse.git -
Envie para seu repositório remoto:
git push mine new_discourse_branch -
Emita um pull request:
- Navegue até seu repositório no GitHub.
- Clique em “Pull Request”.
- Escreva 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 uma descrição.
- Clique em “Send pull request”.
Antes de enviar um pull request, limpe o histórico, revise seus commits e agrupe (squash) alterações menores 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
- Responda aos comentários:
- Esteja receptivo aos comentários e pronto para implementar as alterações sugeridas.
- Lembre-se de que os comentários significam que seu trabalho é valorizado e destinado a ser incluído.
Obrigado por contribuir com o projeto de código aberto Discourse!