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.

Triagem

Issues

• Issues recebidas são triadas pela equipe @open-telemetry/docs-triagers.
• Como primeiro passo, um triador irá ler o título e a descrição da issue e aplicará os seguintes rótulos (labels):
  • Obrigatório: Um rótulo sig:*, lang:* ou docs:* para determinar a (co)propriedade da issue:
    • Um rótulo sig:* caso a issue esteja relacionada a um conteúdo ou uma pergunta que é co-propriedade de um SIG (Special Interest Group, ou Grupo de Interesse Especial). Por exemplo, uma pergunta sobre o Collector será rotulada com sig:collector.
    • Um rótulo lang:* caso a issue esteja relacionada a um conteúdo ou uma pergunta que é co-propriedade de uma localização específica.
    • Um rótulo docs:* caso a issue esteja relacionada a um conteúdo ou uma pergunta que é de propriedade exclusiva da equipe de documentação (SIG Comms):
      • docs
      • docs:admin
      • docs:accessibility
      • docs:analytics-and-seo
      • docs:IA
      • docs:blog
      • docs:cleanup/refactoring
      • docs:upstream, docs:upstream/docsy
      • docs:javascript
      • docs:mobile
      • docs:registry
      • docs:ux
  • Obrigatório: Um rótulo triage:*:
    • triage:accepted, triage:accepted:needs-pr
    • triage:deciding, triage:deciding:blocked, triage:deciding:needs-info
    • triage:rejected, triage:rejected:duplicate, triage:rejected:invalid, triage:rejected:wontfix
  • Obrigatório: Definir o “tipo” da issue da seguinte forma:
    • tipo de issue bug para bugs
    • tipo de issue enhancement para solicitações de recursos
    • rótulo type:question para perguntas
    • rótulo type:copyedit para edições de texto
    • mover a issue para “discussions”, caso pareça ser uma conversa aberta não solucionável
  • Opcional: Um rótulo de estimativa, se aplicável:
    • e0-minutes
    • …
    • e4-months
  • Opcional (e somente definido por mantenedores): Um rótulo de prioridade:
    • p0-critical
    • p1-high
    • p2-medium
    • p3-low
  • Opcional: Um dos seguintes rótulos especiais:
    • good first issue
    • help wanted
    • contribfest
    • maintainers only
    • forever
    • stale
• A automação marcará uma issue em triage:deciding com triage:followup para re-triagem após 14 dias de inatividade em uma issue. O rótulo triage:followup deve ser removido dentro de 7 dias. Mencionar os participantes e remover o rótulo é atividade suficiente.

PRs

• PRs devem ter uma issue vinculada rotulada como triage:accepted, com as seguintes exceções:
  • PRs automáticos
  • correções rápidas por mantenedores/aprovadores
• A automação garantirá que os PRs sejam rotulados e atribuídos para o SIG co-proprietário ou equipe de localização apropriada.
• PRs devem ter os mesmos rótulos de co-propriedade que as issues.
• Se o PR for co-propriedade de um SIG, esse grupo é responsável por fazer uma primeira revisão para garantir que o conteúdo esteja tecnicamente correto.
• Se o PR for co-propriedade de uma equipe de localização, esse grupo é responsável por garantir que a tradução do conteúdo esteja correta.
• A principal responsabilidade da equipe de documentação é garantir que o PR esteja alinhado com os objetivos gerais do projeto, esteja no lugar certo dentro da estrutura e siga os guias de estilo e conteúdo do projeto.
• PRs que estiverem faltando algo para serem mergeados devem ser rotulados adequadamente:
  • missing:cla
  • missing:docs-approval
  • missing:sig-approval
  • blocked
• A automação marcará um PR como stale para solicitar uma nova revisão após 21 dias de inatividade. O rótulo stale deve ser removido dentro de 14 dias. Mencionar os participantes e remover o rótulo é atividade suficiente.
• PRs nunca são fechados automaticamente.

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