Contributing to Discourse development

Documentação Contribuindo
1

:bookmark: Este guia foi elaborado para aqueles que desejam contribuir para o projeto de código aberto Discourse, detalhando a configuração e as convenções necessárias para uma colaboração eficaz.

:person_raising_hand: Nível de usuário exigido: Embora qualquer pessoa 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 núcleo 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:

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 internos do Discourse em porções gerenciáveis e permitem que você comece a contribuir com código facilmente. Comece com:

Para inspiração, explore ideias populares em Feature e Plugin > Extras.

Contribuindo para o núcleo 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 Acordo de Licença de Contribuição do Electronic Discourse Forums. A equipe não pode aceitar legalmente pull requests (PRs) de usuários que não assinaram o CLA.

Aquecendo com tarefas iniciais

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 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

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

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 do tópico.

Melhorando projetos mantidos pelo Discourse

Contribua para outros projetos de código aberto mantidos pelo Discourse. Alguns projetos notáveis incluem:

Convenções de codificação

A nomeação é CRÍTICA

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 é CRÍTICA

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 testes são bem-vindas

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

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

Evite enviar pull requests 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

  1. Clonar o repositório do Discourse:

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

  2. Criar um novo branch:

    cd discourse
git checkout -b novo_branch_discourse

  3. Codificar:

    • Siga as convenções de código existentes que você encontrar no código.
    • Inclua testes e garanta que eles passem.
    • Referencie discussões relevantes no fórum meta do Discourse.

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

    • duas espaços, sem tabs
    • 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 } em vez de { :a => 1 }
    • prefira class << self; def method; end em vez de def self.method para métodos de classe
    • prefira { ... } em vez de do ... end para blocos de linha única, evite usar { ... } para blocos de múltiplas linhas
    • evite return quando não for necessário

  5. Commit:

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

    Nunca deixe uma mensagem de 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 sintaxe 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 as condições de formatação do prettier. O Ruby é verificado com RuboCop. Todas essas verificações são executadas automaticamente nas ações do GitHub sempre que você cria uma pull request para o Discourse.

    • É altamente recomendável instalar nossos ganchos git de pré-commit usando lefthook. Isso será executado automaticamente toda vez que você fizer um commit no núcleo do Discourse e levantará problemas com as várias linguagens e modelos antes que você os envie e tenha que esperar o CI do GitHub ser executado. Execute isso na raiz do seu projeto:
      mkdir .git/hooks
npx 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 para seu remoto:

    git push mine novo_branch_discourse

  9. Emitir uma 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 uma descrição.
    • Clique em “Send pull request”.

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

git fetch origin
git checkout novo_branch_discourse
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 novo_branch_discourse
  1. Responder ao feedback:
    • Seja responsivo 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 de código aberto Discourse!

73 curtidas