Contribuidores da documentação do Kubernetes podem:
Melhorar o conteúdo existente
Criar novo conteúdo
Traduzir a documentação
Gerenciar e publicar a documentação como parte do ciclo de lançamento do Kubernetes
Começando
Qualquer pessoa pode abrir uma issue sobre a documentação, ou contribuir com uma mudança por meio de um pull request (PR) para o repositório do Github kubernetes/website.
É recomendável que você se sinta confortável com git e
Github para trabalhar efetivamente na comunidade Kubernetes.
Algumas tarefas requerem mais confiança e mais acessos na organização do Kubernetes.
Veja Participando no SIG Docs para mais detalhes
sobre funções e permissões.
O SIG Docs é um grupo de contribuidores que publica e mantém
a documentação e o site do Kubernetes. Se envolver com o SIG Docs é uma ótima forma de contribuidores Kubernetes (pessoas desenvolvedoras de features ou outros) terem um grande impacto dentro do projeto Kubernetes.
A comunicação do SIG Docs é feita de diferentes formas:
Para contribuir com a comunidade Kubernetes por meio de fóruns on-line, como Twitter ou Stack Overflow, ou aprender sobre encontros locais e eventos do Kubernetes, visite a area de comunidade Kubernetes.
Para contribuir com o desenvolvimento de novas funcionalidades, leia o cheatsheet do colaborador para começar.
Leia o cheatsheet de contribuidor para saber mais sobre as funcionalidades de desenvolvimento do Kubernetes.
Qualquer pessoa pode revisar um pull request da documentação.
Visite a seção pull requests no repositório do site Kubernetes para ver os pull requests abertos.
Revisar os pull requests da documentação é uma ótima maneira de se apresentar à comunidade Kubernetes.
Isso ajuda você a aprender a base de código e construir a confiança com outros colaboradores.
Comente os aspectos positivos dos PRs, bem como mudanças.
Seja empático e cuidadoso, observe como sua avaliação pode ser recebida.
Assuma boas intenções e faça perguntas esclarecedoras.
Colaboradores experientes, considere trabalhar em par com os novos colaboradores cujo trabalho requer grandes mudanças.
Processo de revisão
Em geral, revise os pull requests de conteúdo e estilo em inglês.
A Figura 1 descreve as etapas para o processo de revisão.
Seguem os detalhes para cada etapa.
flowchart LR
subgraph fourth[Começar revisão]
direction TB
S[ ] -.-
M[adicionar comentários] --> N[revisar mudanças]
N --> O[novos colaboradores devem escolher Comment]
end
subgraph third[Selecionar PR]
direction TB
T[ ] -.-
J[leia a descrição e comentários]--> K[visualize as mudanças no ambiente de pré-visualização do Netlify]
end
A[Revise a lista de PR abertos]--> B[Filtre os PRs abertos pela label]
B --> third --> fourth
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,J,K,M,N,O grey
class S,T spacewhite
class third,fourth white
Filtre os PRs abertos usando um ou todos os labels seguintes:
cncf-cla: yes (Recomendado): PRs enviados por colaboradores que não assinaram o CLA não podem ser feito o merge. Consulte Assinar o CLA para obter mais informações.
language/pt (Recomendado): Filtro para PRs em português.
size/<size>: Filtro para PRs com um determinado tamanho. Se você é novo, comece com PRs menores.
Além disso, certifique-se que o PR não esteja marcado como work in progress. Os PRs que usam o labelwork in progress ainda não estão prontos para revisão.
Depois de selecionar um PR para revisar, entenda a mudança:
Lendo a descrição do PR para entender as alterações feitas e ler quaisquer issues vinculadas
Lendo quaisquer comentários de outros revisores
Clicando na aba Files changed para ver os arquivos e linhas alteradas
Pré-visualizar as alterações ambiente de pré-visualização do Netlify, rolando até a seção PR's build check na parte inferior da aba Conversation.
Aqui está uma captura da tela (isso mostra a área de trabalho do site GitHub; se você estiver revisando em um tablet ou smartphone, a interface web do usuário GitHub será um pouco diferente):
Para abrir a visualização, selecione o link Details da linha deploy/netlify na lista de verificações.
Vá para a aba Files changed para iniciar sua revisão.
Clique no símbolo + ao lado da linha que você deseja comentar.
Preencha com todos os comentários que você tenha sobre a linha e clique em Add single comment (se você tiver apenas um comentário para fazer) ou Start a review (se você tiver vários comentários para fazer)
Quando terminar, clique em Review changes na parte superior da página.
Aqui, você pode adicionar um resumo da sua revisão (e deixar alguns comentários positivos para o colaborador!).
Por favor, sempre use o "Comentário"
Evite clicar no botão "Request changes" ao concluir sua revisão.
Se você quiser bloquear o merge do PR antes que outras alterações sejam realizadas, você pode deixar um comentário "/hold".
Mencione por que você está definindo o bloqueio e, opcionalmente, especifique as condições sob as quais o bloqueio pode ser removido por você ou por outros revisores.
Evite clicar no botão "Approve" ao concluir sua revisão.
Deixar um comentário "/approve" é recomendado na maioria dos casos.
Checklist para revisão
Ao revisar, use como ponto de partida o seguinte.
Linguagem e gramática
Existe algum erro óbvio na linguagem ou gramática? Existe uma maneira melhor de expressar algo?
Concentre-se na linguagem e na gramática nas partes que o autor está mudando na página.
A menos que o autor esteja claramente com o objetivo de atualizar a página inteira, ele não tem obrigação de corrigir todos os problemas na página.
Quando um PR atualiza uma página existente, você deve se concentrar em revisar as partes que estão sendo atualizadas na página.
Esse conteúdo alterado deve ser revisado quanto à correção técnica e editorial.
Se você encontrar erros na página que não se relacionam diretamente com o que o autor do PR está tentando resolver, ele deve ser tratado em uma issue separada (primeiro, verifique se não existe uma issue existente sobre isso).
Cuidado com os pull requests que movem conteúdo.
Se um autor renomear uma página ou combinar duas páginas, nós (Kubernetes SIG Docs) geralmente evitamos pedir a esse autor que corrija todas as questões gramaticais ou ortográficas que poderíamos identificar dentro desse conteúdo movido.
Existem palavras complicadas ou arcaicas que podem ser substituídas por uma palavra mais simples?
Existem palavras, termos ou frases em uso que podem ser substituídos por uma alternativa não discriminatória?
A escolha da palavra e sua capitalização seguem o guia de estilo?
Existem frases longas que podem ser mais curtas ou menos complexas?
Existem parágrafos longos que podem funcionar melhor como uma lista ou tabela?
Conteúdo
Existe conteúdo semelhante em outro lugar no site Kubernetes?
O conteúdo está excessivamente vinculado a uma documentação externa, de um fornecedor individual ou de um código não aberto?
Website
Esse PR alterou ou removeu um título da página, slug/alias ou link?
Em caso afirmativo, existem links quebrados como resultado deste PR?
Existe outra opção, como alterar o título da página sem alterar o slug?
O PR apresenta uma nova página? Caso afirmativo:
A página está usando corretamente o tipo de conteúdo e os códigos relacionados ao Hugo?
A página aparece corretamente na navegação da seção (ou em geral)?
As alterações aparecem na visualização do Netlify? Esteja particularmente atento a listas, blocos de código, tabelas, notas e imagens.
Outro
Cuidado com as edições triviais;
se você observar uma mudança que entender ser uma edição trivial, por favor, marque essa política (ainda não há problema em aceitar a alteração se for genuinamente uma melhoria).
Incentive os autores que estão fazendo correções de espaço em branco a fazê-lo no primeiro commit de seu PR e, em seguida, adicione outras alterações além disso.
Isso facilita as revisões e o merge.
Cuidado especialmente com uma mudança trivial que aconteça em um único commit, juntamente com uma grande quantidade de limpeza dos espaços em branco (e se você observar isso, incentive o autor a corrigi-lo).
Como revisor, se você identificar pequenos problemas com um PR que não são essenciais para o significado, como erros de digitação ou espaços em branco incorretos, sinalize seus comentários com nit:.
Isso permite que o autor saiba que esta parte do seu feedback não é uma crítica.
Se você estiver considerando um pull request e todo o feedback restante estiver marcado como um nit, você pode realizar o merge do PR de qualquer maneira.
Nesse caso, muitas vezes é útil abrir uma issue sobre os nits restantes.
Considere se você é capaz de atender aos requisitos para marcar esse nova issue como uma Good First Issue; se você puder, esses são uma boa fonte.
2 - Visão geral do estilo da documentação
Os tópicos desta seção fornecem orientações gerais para o estilo de escrita,
formatação e organização do conteúdo, e como utilizar as customizações do Hugo
específicas para a documentação do Kubernetes.
3 - Visualizando Analytics do Site
Essa página contém informações sobre a dashboard de analystics do kubernetes.io.
Essa dashboard foi feita usando
o Google Data Studio e possui informações coletadas do
kubernetes.io usando o Google Analytics.
Usando a dashboard
Por padrão, a dashboard mostra todos os analytics coletados nos últimos 30 dias. Use o seletor de data
para ver dados de outros intervalos de data. Outras
opções de filtros permitem que você veja dados baseados
em localização do usuário para acessar o site, a tradução
da documentação usada e outros.
Se você identificar um problema com essa dashboard ou quer solicitar qualquer melhoria, abra uma issue no repositório.
