Enviando conteúdo

Para contribuir com novos conteúdos ou melhorar a documentação existente, submeta um pull request (PR):

• Se sua alteração for pequena ou você não estiver familiarizado com o Git, veja Usando o GitHub para aprender como editar uma página.
• Caso contrário, consulte Trabalhando localmente para aprender como fazer alterações no seu próprio ambiente de desenvolvimento local.

A figura a seguir ilustra como contribuir com nova documentação.

flowchart LR
    subgraph first[Como contribuir]
    direction TB
       T[ ] -.-
       B[Fazer cópia _fork_ do repositório no GitHub] --- C[Escrever documentação em markdown<br>e construir o site com Hugo]
       C --- D[Enviar o código-fonte para o _fork_]
       D --- E[Abrir um _pull request_]
       E --- F[Assinar o CNCF CLA]
    end

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,C,D,E,F,G,H grey
class S,T spacewhite
class first,second white

Figura 1. Contribuindo com novo conteúdo.

Usando o GitHub

Editar e enviar alterações pelo navegador

Se você tem menos experiência com fluxos de trabalho do Git, aqui está um método mais fácil de preparar e abrir um novo pull request (PR). A Figura 2 descreve os passos, e os detalhes seguem abaixo.

flowchart LR
A([fa:fa-user Novo<br>Contribuidor]) --- id1[(open-telemetry/opentelemetry.io<br>GitHub)]
subgraph tasks[Alterações usando o GitHub]
direction TB
    0[ ] -.-
    1[1\. Editar esta página] --> 2[2\. Usar o editor de markdown<br>do GitHub para fazer alterações]
    2 --> 3[3\. Preencher o formulário Propor alteração de arquivo]

end
subgraph tasks2[ ]
direction TB
4[4\. Selecionar Propor alteração de arquivo] --> 5[5\. Selecionar Criar pull request] --> 6[6\. Preencher Abrir um pull request]
6 --> 7[7\. Selecionar Criar pull request]
end

id1 --> tasks --> tasks2

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,1,2,3,4,5,6,7 grey
class 0 spacewhite
class tasks,tasks2 white
class id1 k8s

Figura 2. Etapas para abrir um PR usando o GitHub.

1. Na página onde você vê o problema, selecione a opção Editar esta página no painel de navegação à direita.

2. Se você não for membro do projeto, o GitHub oferece a opção de criar um fork do repositório. Selecione Fazer fork deste repositório.

3. Faça suas alterações no editor do GitHub.

4. Preencha o formulário Propor alteração de arquivo.

5. Selecione Propor alteração de arquivo.

6. Selecione Criar pull request.

7. A tela Abrir um pull request aparece. Sua descrição ajuda os revisores a entenderem sua alteração.

8. Selecione Criar pull request.

Antes de mesclar um pull request, os membros da comunidade OpenTelemetry revisam e aprovam.

Se um revisor pedir para você fazer alterações:

1. Vá para a aba Arquivos alterados.
2. Selecione o ícone de lápis (editar) em qualquer arquivo alterado pelo pull request.
3. Faça as alterações solicitadas. Se houver uma sugestão de código, aplique-a.
4. Commit as alterações.

Quando sua revisão estiver completa, um revisor mescla seu PR e suas alterações ficam disponíveis alguns minutos depois.

Corrigindo falhas na verificação do PR

Depois de enviar um PR, o GitHub executa algumas verificações de compilação. Certas falhas de verificação, como problemas de formatação, podem ser corrigidas automaticamente.

Adicione o seguinte comentário ao seu PR:

/fix:all

Isso fará com que o bot OpenTelemetry tente corrigir os problemas de compilação. Ou você pode emitir um dos seguintes comandos de correção para resolver uma falha específica:

fix:dict
fix:expired
fix:filenames
fix:format
fix:htmltest-config
fix:i18n
fix:markdown
fix:refcache
fix:submodule
fix:text

Trabalhando localmente

Se você tem mais experiência com Git, ou se suas alterações são maiores do que algumas linhas, trabalhe a partir de um fork local.

Certifique-se de que você tenha git instalado no seu computador. Você também pode usar uma interface de usuário para o Git.

A Figura 3 mostra os passos a seguir quando você trabalha a partir de um fork local. Os detalhes de cada etapa seguem abaixo.

flowchart LR
1[Faça o _fork_ do repositório<br>open-telemetry/opentelemetry] --> 2[Crie um clone<br>e configure a branch remota]
subgraph changes[Suas alterações]
direction TB
S[ ] -.-
3[Crie uma branch<br>exemplo: minha_nova_branch] --> 3a[Faça alterações usando<br>um editor de texto] --> 4["Visualize suas alterações<br>localmente usando Hugo<br>(localhost:1313)"]
end
subgraph changes2[_Commit_ / Push]
direction TB
T[ ] -.-
5[_Commit_ suas alterações] --> 6[Envie o _commit_ para<br>origin/minha_nova_branch]
end

2 --> changes --> changes2

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class 1,2,3,3a,4,5,6 grey
class S,T spacewhite
class changes,changes2 white

_Figura 3. Trabalhando a partir de um fork local para fazer suas alterações._

Faça o fork do repositório

1. Navegue até o repositório opentelemetry.io.
2. Selecione Fork.

Clone e defina o repositório de origem (upstream)

1. Em uma janela de terminal, clone seu fork e instale as dependências:

   git clone git@github.com:<seu_nome_de_usuario_no_github>/opentelemetry.io.git
   cd opentelemetry.io
   npm install
   

2. Defina o repositório open-telemetry/opentelemetry.io como o remoto upstream:

   git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git
   

3. Confirme seus repositórios origin e upstream:

   git remote -v
   

   A saída é semelhante a:

   origin	git@github.com:<seu_nome_de_usuario_no_github>/opentelemetry.io.git (fetch)
   origin	git@github.com:<seu_nome_de_usuario_no_github>/opentelemetry.io.git (push)
   upstream	https://github.com/open-telemetry/opentelemetry.io.git (fetch)
   upstream	https://github.com/open-telemetry/opentelemetry.io.git (push)
   

4. Obtenha commits do origin/main do seu fork e upstream/main do repositório open-telemetry/opentelemetry.io:

   git fetch origin
   git fetch upstream
   

   Isso garante que seu repositório local esteja atualizado antes de você começar a fazer alterações. Envie alterações do upstream para o origin regularmente para manter seu fork sincronizado com o upstream.

Crie uma branch (ramificação)

1. Crie uma nova branch. Este exemplo assume que a branch base é upstream/main:

   git checkout -b <minha_nova_branch> upstream/main
   

2. Faça suas alterações usando um editor de código ou texto.

A qualquer momento, use o comando git status para ver quais arquivos você alterou.

Commit suas alterações

Quando você estiver pronto para enviar um pull request, confirme suas alterações.

1. No seu repositório local, verifique quais arquivos você precisa confirmar:

   git status
   

   A saída é semelhante a:

   On branch <minha_nova_branch>
   Your branch is up to date with 'origin/<minha_nova_branch>'.
   
   Changes not staged for _commit_:
   (use "git add <file>..." to update what will be _committed_)
   (use "git checkout -- <file>..." to discard changes in working directory)
   
   modified:   content/en/docs/file-you-are-editing.md
   
   no changes added to _commit_ (use "git add" and/or "git commit -a")
   

2. Adicione os arquivos listados em Alterações não preparadas para commit (Changes not staged for commit) ao commit:

   git add <nome_do_seu_arquivo>
   

   Repita isso para cada arquivo.

3. Depois de adicionar todos os arquivos, crie um commit:

   git commit -m "Sua mensagem de _commit_"
   

4. Envie sua branch local e seu novo commit para seu fork remoto:

   git push origin <minha_nova_branch>
   

5. Assim que as alterações forem enviadas, o GitHub avisará que você pode criar um PR.

Abre um novo PR

A Figura 4 mostra os passos para abrir um PR do seu fork para opentelemetry.io.

flowchart LR
subgraph first[ ]
direction TB
1[1\. Vá para o repositório opentelemetry.io] --> 2[2\. Selecione Novo Pull Request]
2 --> 3[3\. Selecione comparar entre _forks_]
3 --> 4[4\. Selecione seu _fork_ no<br>menu suspenso do repositório de origem]
end
subgraph second [ ]
direction TB
5[5\. Selecione sua branch no<br>menu suspenso de comparação] --> 6[6\. Selecione Criar Pull Request]
6 --> 7[7\. Adicione uma descrição<br>ao seu PR]
7 --> 8[8\. Selecione Criar pull request]
end

first --> second

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
class 1,2,3,4,5,6,7,8 grey
class first,second white

Figura 4. Etapas para abrir um PR do seu fork para opentelemetry.io.

1. Em um navegador da web, vá para o repositório opentelemetry.io.

2. Selecione Novo Pull Request.

3. Selecione comparar entre forks.

4. No menu suspenso repositório de origem, selecione seu fork.

5. No menu suspenso comparar, selecione sua branch.

6. Selecione Criar Pull Request.

7. Adicione uma descrição para o seu pull request:

   • Título (50 caracteres ou menos): Resuma a intenção da alteração.
   • Descrição: Descreva a alteração em mais detalhes.
     • Se houver uma issue relacionada no GitHub, inclua Fixes #12345 ou Closes #12345 na descrição para que a automação do GitHub feche a issue mencionada após o merge do PR. Se houver outros PRs relacionados, vincule-os também.
     • Se você quiser aconselhamento sobre algo específico, inclua na descrição quaisquer perguntas que você gostaria que os revisores levassem em conta durante a revisão.

8. Selecione o botão Criar pull request.

Seu pull request está disponível em Pull requests.

Após a abertura de um PR, o GitHub executa testes automatizados e tenta implantar uma prévia usando Netlify.

• Se a compilação do Netlify falhar, selecione Detalhes (Details) para mais informações.
• Se a compilação do Netlify for bem-sucedida, selecione Detalhes para abrir uma versão do site OpenTelemetry com suas alterações aplicadas. É assim que os revisores verificam suas alterações.

Outras verificações também podem falhar. Veja a lista de todas as verificações de PR.

Corrija problemas

Antes de enviar uma alteração para o repositório, execute o seguinte comando e (i) resolva quaisquer problemas relatados, (ii) commit quaisquer arquivos alterados pelo script:

npm run test-and-fix

Para testar e corrigir separadamente todos os problemas com seus arquivos, execute:

npm run test    # Verifica, mas não atualiza nenhum arquivo
npm run fix:all # Pode atualizar arquivos

Para listar os scripts NPM disponíveis, execute npm run. Veja verificações de PR para mais informações sobre verificações de pull request e como corrigir erros automaticamente.

Visualize suas alterações

Visualize suas alterações localmente antes de enviá-las ou abrir um pull request. Uma prévia permite que você detecte erros de compilação ou problemas de formatação do Markdown.

Para construir e disponibilizar o site localmente com o Hugo, execute o seguinte comando:

npm run serve

Navegue até http://localhost:1313 em seu navegador da web para ver a prévia local. O Hugo monitora as alterações e reconstrói o site conforme necessário.

Para parar a instância local do Hugo, volte ao terminal e digite Ctrl+C, ou feche a janela do terminal.

Implantações de site e prévias de PR

Se você enviar um PR, o Netlify criará uma prévia de implantação para que você possa revisar suas alterações. Assim que ocorrer o merge do seu PR, o Netlify implanta o site atualizado no servidor de produção.

Nota: As prévias de PR incluem páginas de rascunho, mas as compilações de produção não.

Para ver logs de implantação e mais, visite o dashboard do projeto - login no Netlify é necessário.

Diretrizes de PR

Antes que um PR seja mesclado, às vezes são necessárias algumas iterações de revisão e edição. Para nos ajudar e a si mesmo a tornar esse processo o mais fácil possível, pedimos que você adira ao seguinte:

• Se o seu PR não for uma correção rápida, trabalhe a partir de um fork: Clique no botão Fork na parte superior do repositório e clone o fork localmente. Quando estiver pronto, envie um PR para o repositório upstream.
• Não trabalhe a partir da branch main do seu fork, mas crie uma branch específica para o PR.
• Certifique-se de que os mantenedores estão autorizados a aplicar alterações ao seu pull request.

Alterações dos revisores

Às vezes, os revisores fazem commits no seu pull request. Antes de fazer qualquer outra alteração, obtenha esses commits.

1. Obtenha commits do seu fork remoto e faça o rebase em sua branch de trabalho:

   git fetch origin
   git rebase origin/<seu-nome-da-branch>
   

2. Após o rebase, execute um force-push contendo as novas alterações para seu fork:

   git push --force-with-lease origin <seu-nome-da-branch>
   

Você também pode resolver conflitos de merge (mesclar) pela interface do GitHub.

Conflitos de merge e rebase

Se outro colaborador fizer commits no mesmo arquivo em outro PR, isso pode criar um conflito de merge. Você deve resolver todos os conflitos de merge em seu PR.

1. Atualize seu fork e faça rebase em sua branch local:

   git fetch origin
   git rebase origin/<seu-nome-da-branch>
   

   Em seguida, execute um force-push contendo as alterações para seu fork:

   git push --force-with-lease origin <seu-nome-da-branch>
   

2. Obtenha alterações do upstream/main do repositório open-telemetry/opentelemetry.io e faça rebase de sua branch:

   git fetch upstream
   git rebase upstream/main
   

3. Inspecione os resultados do rebase:

   git status
   

   Isso resulta em vários arquivos marcados como conflitantes.

4. Abra cada arquivo em conflito e procure os marcadores de conflito: >>>, <<<, e ===. Resolva o conflito e exclua o marcador de conflito.

   Para mais informações, veja Como os conflitos são apresentados.

5. Adicione os arquivos ao conjunto de alterações:

   git add <nome_do_arquivo>
   

6. Continue o rebase:

   git rebase --continue
   

7. Repita as etapas 2 a 5 conforme necessário.

   Após aplicar todos os commits, o comando git status mostra que o rebase está completo.

8. Execute um force-push da branch para seu fork:

   git push --force-with-lease origin <seu-nome-da-branch>
   

   O pull request não mostra mais conflitos.

Requisitos de merge

O merge dos pull requests ocorrem quando são cumpridos os seguintes critérios:

• Todas as revisões por aprovadores, mantenedores, membros do comitê técnico ou especialistas no assunto têm o status “Aprovado”.
• Nenhuma conversa não resolvida.
• Aprovado por pelo menos um aprovador.
• Sem falhas nas verificações de PR.
• A branch do PR está atualizada com a branch base.
• As alterações na página do doc não abrangem localidades.

Importante

Não se preocupe muito com as falhas nas verificações de PR. Os membros da comunidade ajudarão você a corrigi-las, fornecendo instruções sobre como corrigi-las ou corrigindo-as em seu nome.