Práticas do SIG para aprovadores e mantenedores

Esta página inclui diretrizes e algumas práticas comuns utilizadas por aprovadores e mantenedores.

Integração

Quando uma pessoa colaboradora assume um papel com mais responsabilidade na documentação (como aprovador ou mantenedor), será integrada pelos aprovadores e mantenedores existentes:

• Será adicionada ao grupo docs-approvers (ou docs-maintainers).
• Será adicionada aos canais de Slack #otel-comms, #otel-maintainers e canais internos privados.
• Será solicitada a se inscrever nos convites de calendário para as reuniões do SIG de Comunicações e das reuniões de Mantenedores.
• Será solicitada a verificar se o horário atual da reunião do SIG Comms funciona para ela. Caso contrário, deverá colaborar com os demais aprovadores e mantenedores para encontrar um horário viável para todos.
• Será solicitada a revisar os diferentes recursos disponíveis para contribuidores:
  • Recursos da Comunidade, especialmente o documento sobre Níveis de Participação na Comunidade e o Guia de Redes Sociais.
  • Diretrizes de Contribuição — como parte desse processo, a pessoa revisará os documentos e poderá sugerir melhorias por meio de issues ou pull requests.

Outros recursos valiosos para revisão:

• Documentação do Hugo
• Documentação do Docsy
• Diretrizes de Marketing, incluindo as diretrizes de uso de marca e marca registrada da Linux Foundation. Esses recursos são especialmente importantes ao revisar entradas para o registro, integrações, fornecedores, adotantes ou distribuições.

Colaboração

• Aprovadores e mantenedores têm horários e circunstâncias de trabalho diferentes. Por isso, toda comunicação é considerada assíncrona. Eles não devem se sentir obrigados a responder fora de seu horário normal.
• Quando um aprovador ou mantenedor não puder contribuir por um período prolongado (mais do que alguns dias ou uma semana), deve comunicar isso pelo canal #otel-comms e atualizar seu status no GitHub.
• Aprovadores e mantenedores seguem o Código de Conduta da OTel e os Valores da Comunidade. Eles devem ser amigáveis e prestativos com os contribuidores. Em caso de conflito, mal-entendido ou qualquer outro tipo de situação que deixe um aprovador/mantenedor desconfortável, eles podem se afastar da conversa, issue ou PR e pedir que outra pessoa assuma.

Revisão de Código

Geral

• Se a branch do PR estiver “desatualizada com a branch base” (out-of-date with the base branch), não é necessário atualizá-la continuamente: toda atualização dispara novamente os testes de CI! Geralmente, é suficiente atualizar antes de fazer o merge.
• PRs de pessoas que não são mantenedoras nunca devem atualizar submódulos git. Isso pode acontecer por engano. Informe ao autor que não há problema, que nós iremos corrigir antes do merge, mas que no futuro deve usar um fork atualizado.
• Se o contribuidor estiver com problemas para assinar o CLA ou usou o e-mail errado em algum commit, solicite a correção ou o rebase do PR. No pior dos casos, feche e reabra o PR para disparar nova verificação do CLA.
• Palavras desconhecidas para o cspell devem ser adicionadas pelo autor do PR à lista local de ignore da página. Apenas aprovadores e mantenedores adicionam termos globais.

PRs co-gerenciados

PRs que modificam documentação co-gerenciada por algum SIG (collector, demo, linguagem específica etc.) devem buscar duas aprovações: uma de aprovador de docs e outra de aprovador do SIG:

• O aprovador de docs deve marcar o PR com sig:<nome> e marcar o grupo -approvers do SIG.
• Após revisar e aprovar, o aprovador de docs pode adicionar o label sig-approval-missing, sinalizando ao SIG que ele deve revisar o PR.
• Se não houver aprovação do SIG dentro de um prazo razoável (geralmente duas semanas, podendo ser menor em casos urgentes), o mantenedor da documentação pode usar seu próprio julgamento para fazer o merge.

PRs de bots

PRs criadas por bots seguem estas práticas:

• PRs que atualizam automaticamente versões no registro podem ser corrigidos, aprovados e mergeados imediatamente.
• PRs que atualizam automaticamente versões de SDKs, instrumentações zero-code ou o collector podem ser aprovadas e mergeados, a menos que o SIG correspondente solicite adiamento.
• PRs que atualizam automaticamente versões de especificações frequentemente exigem atualizações em scripts para que os testes de CI passem. Nesse caso, @chalin cuidará do PR. Caso contrário, também podem ser aprovados e mergeados, exceto quanto o SIG correspondente sinaliza que o merge deve ser adiado.

PRs de tradução

PRs com mudanças em traduções devem ter duas aprovações: uma de aprovador de docs e outra de aprovador de tradução. As mesmas práticas sugeridas para PRs co-gerenciados se aplicam aqui.

Fazendo merge dos PRs

Mantenedores podem seguir este fluxo para dar merge nos PRs:

• Verifique se o PR tem todas as aprovações e todos os testes de CI passaram.

• Se a branch estiver desatualizada, atualize via UI do GitHub.

• A atualização disparará os testes de CI para serem executados novamente. Aguarde que todos os testes passem ou use o seguinte comando para rodar os testes e dar merge em segundo plano:

  export PR=<ID DO PR>; gh pr checks ${PR} --watch && gh pr merge ${PR} --squash