Ir para o conteúdo principal

Contribuindo

Docusaurus 2 está em desenvolvimento no momento. Temos adotantes pioneiros que já começaram a usá-lo. Estamos agora dando as boas-vindas a contribuidores para colaborar no próximo Docusaurus.

O site Guias de Código Aberto tem uma coleção de recursos para indivíduos, comunidades e empresas que querem aprender como executar e contribuir para um projeto de código aberto. Colaboradores e pessoas novas no código aberto acharão os seguintes guias especialmente úteis:

Código de Conduta

O Facebook adotou um Código de Conduta que esperamos que os participantes do projeto sigam. Por favor, leia o texto completo para que você entenda quais ações serão e não serão toleradas.

Se envolver

Existem muitas maneiras de contribuir para o Docusaurus, e muitas delas não envolvem a escrita de nenhum código. Aqui estão algumas ideias para começar:

  • Comece a usar o Docusaurus 2! Vá até os guias de Primeiros passos . Tudo funciona conforme o esperado? Caso contrário, estamos sempre em busca de melhorias. Deixe-nos saber abrindo uma issue.
  • Procure pelos v2.0 issues. Se você encontrar um problema que deseja corrigir, abra um pull request. Problemas marcados como Good first issue são um bom lugar para começar.
  • Ajude-nos a melhorar a documentação. Registre um problema se você encontrar algo que seja confuso ou possa ser melhorado. Também temos um problema abrangente para documentos v2, onde estamos planejando e trabalhando em todos os documentos v2. Você pode adotar uma peça de documento lá para trabalhar.
  • Dê uma olhada nos recursos solicitados por outras pessoas na comunidade e considere abrir uma solicitação pull se encontrar algo que deseja trabalhar.

As contribuições são muito bem-vindas. Se acha que precisa de ajuda para planejar a sua contribuição, por favor, nos deixe no Twitter em @docusaurus e nos avise que você está procurando ajuda.

Entre no nosso canal do Discord

To participate in Docusaurus 2 dev, join the #contributors channel.

Nosso processo de desenvolvimento

O Docusaurus usa o GitHub como sua fonte da verdade. A equipe principal estará trabalhando diretamente lá. Todas as alterações serão públicas desde o início.

Quando uma alteração feita no GitHub for aprovada, ela será verificada por nosso sistema de integração contínua, CircleCI.

Relatando novas issues

Ao abrir uma nova issue, sempre certifique-se de preencher o modelo de issue. Esta etapa é muito importante! Não fazer isso pode fazer com que seu problema não seja resolvido em tempo hábil. Não leve isso para o lado pessoal se isso acontecer e sinta-se à vontade para abrir um nova issue depois de reunir todas as informações exigidas pelo modelo.

  • Um problema, um bug: Por favor, reporte um único bug por issue.
  • Forneça etapas de reprodução: Liste todos os passos necessários para reproduzir o problema. A pessoa que estiver lendo seu relatório de erros deve ser capaz de seguir estas etapas para reproduzir seu problema com um mínimo de esforço.

Relatando bugs

Usamos issues no GitHub para nossos bugs públicos. Se você gostaria de relatar um problema, dê uma olhada e veja se alguém já abriu um problema a esse respeito. Se você tem certeza de que esse é um novo bug não reportado, você pode enviar um relatório de erros.

Se você tiver dúvidas sobre como usar o Docusaurus, entre em contato com a conta do Twitter do Docusaurus em @docusaurus, e faremos o nosso melhor para responder às suas perguntas.

Você também pode arquivar issues como solicitações de recursos ou aprimoramentos. Se você ver qualquer coisa que queira ser implementada, crie uma issue com modelo de recurso

Reportando erros de segurança

O Facebook tem um programa de recompensas para a divulgação segura de bugs de segurança. Com isso em mente, não registre questões públicas; siga o processo descrito nessa página.

Testando novos recursos

Você pode se tornar um dos primeiros a adotar novos recursos usando a tag @canary npm dist tag e testar novos recursos em seu site assim que o pull-request for aceito. Isso nos ajuda a detectar problemas antes do lançamento oficial.

Trabalhando no código Docusaurus

Instalação

  1. Certifique-se de que você tem o Yarn instalado
  2. Após clonar o repositório, execute yarn install na raiz do repositório
  3. Para iniciar um servidor de desenvolvimento local servindo os documentos Docusaurus, vá para o diretório do website e execute yarn start

Mensagens de commit semântico

Veja como uma pequena alteração no seu estilo de mensagem do commit pode fazer de você um programador melhor.

Formato: <type>(<scope>): <subject>

<scope> é opcional

Exemplo

feat: allow overriding of webpack config
^--^ ^------------^
| |
| +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

Os vários tipos de commits:

  • feat: (novo recurso para o usuário, não um novo recurso para script de build)
  • fix: (correção de bug para o usuário, não uma correção para um script de build)
  • docs: (mudanças na documentação)
  • style: (formatação, ponto e vírgula faltando, etc; sem mudança de código de produção)
  • refactor: (refatorar código de produção, por exemplo. renomeando uma variável)
  • test: (adicionar testes ausentes, refatorar testes; sem mudança de código de produção)
  • chore: (atualização de tarefas grunhidas etc; sem mudança de código de produção)

Use letras minúsculas, não letras maiúsculas!

Convenções de código

Guia de estilo

Prettier irá detectar a maioria dos problemas de estilo que possam existir em seu código. Você pode verificar o status do estilo do seu código simplesmente executando npm run prettier.

No entanto, ainda existem alguns estilos que a Prettier não consegue pegar.

Geral

  • Mais importante: Olhe em volta. Combine o estilo que você vê usado no resto do projeto. Isso inclui formatação, nomeando arquivos, nomeando coisas no código, nomeando coisas na documentação.
  • "Atributivo"

Documentação

  • Não quebra linhas com 80 caracteres - configure seu editor para quebra automática ao editar a documentação.

Pull requests

Seu primeiro pull request

Então você decidiu contribuir com o código de volta para o upstream abrindo uma pull request. Você investiu uma boa parte do tempo e nós agradecemos por isso. Faremos o melhor para trabalhar com você e obter o PR analisado.

Trabalhando no seu primeiro Pull Request? Você pode aprender como usar esta série de vídeos grátis:

Como Contribuir com um Projeto de Código Aberto no GitHub

Temos uma lista de problemas amigáveis para iniciantes para ajudá-lo a ficar com os pés molhados na base de código do Docusaurus e familiarizar-se com o nosso processo de contribuição. Este é um ótimo lugar para começar.

Propondo uma alteração

Se você gostaria de solicitar um novo recurso ou aprimoramento, mas ainda não está pensando em abrir um pull request, você também pode arquivar um problema com o modelo de funcionalidade.

Se você pretende mudar a API pública (por exemplo, algo no docusaurus.config. s), ou faça quaisquer alterações não-triviais na implementação, nós recomendamos arquivamento de um problema com modelo de proposta e incluindo [Proposal] no título. Isso nos permite chegar a um acordo sobre sua proposta antes que você se esforce significativamente. Esses tipos de problemas devem ser raros.

Se você está apenas corrigindo um bug, não há problema em enviar uma solicitação de pull imediatamente, mas ainda recomendamos registrar um problema detalhando o que você está corrigindo. Isso é útil caso não aceitemos essa correção específica, mas desejemos acompanhar o problema.

Enviando um pull request

Pequenos pull requests são muito mais fáceis de revisar e mais propensos a serem mesclados. Certifique-se de que o PR faça apenas uma coisa, caso contrário, divida-o. É recomendável seguir este estilo da mensagem de commit.

Certifique-se de que o seguinte é feito ao enviar uma pull request:

  1. Faça um fork do repositório e crie o seu branch a partir do main.
  2. Adicione o aviso de direitos autorais ao topo de qualquer código de novos arquivos que você adicionou.
  3. Descreva seu plano de teste na descrição do pull request. Certifique-se de testar suas alterações!
  4. Certifique-se suas analises de código lints (yarn prettier && yarn lint).
  5. Certifique-se de que seus testes Jest passam (yarn test).
  6. Se ainda não o fez, assine o CLA.

Todos os pull requests devem ser abertos no branch main.

Plano de teste

Um bom plano de teste tem os comandos exatos que você executou e a sua saída, fornece capturas de tela ou vídeos se a pull request mudar a interface do usuário.

  • Se você mudou a APIs, atualize a documentação.

Quebrando mudanças

Ao adicionar uma nova alteração de quebra, siga este modelo em sua pull request:

### New breaking change here

- **Who does this affect**:
- **How to migrate**:
- **Why make this breaking change**:
- **Severity (number of people affected x effort)**:

Copie e cole isso no topo de seu(s) novo(s) arquivo(s):

/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/

Acordo de Licença do Colaborador (CLA)

Para aceitar o seu pull request, precisamos que você envie um CLA. Você só precisa fazer isso uma vez, então se você fez isso para outro projeto de código aberto do Facebook, você está pronto para ir. Se você estiver enviando uma solicitação pull pela primeira vez, o Facebook GitHub Bot responderá com um link para o formulário CLA. Você também pode completar seu CLA aqui.

O que acontece depois?

A equipe principal do Docusaurus irá monitorar os pull requests. Ajude-nos, mantendo as pull requests consistentes seguindo as diretrizes acima.

Licença

Ao contribuir com o Docusaurus, você concorda que suas contribuições serão licenciadas sob a licença MIT.