Contribua com a documentação do Kubernetes

O Kubernetes agradece as melhorias de todos os contribuidores, novos e experientes!

Este site é mantido pelo Kubernetes SIG Docs.

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.

Para se envolver com a documentação:

1. Assine o Contrato de Licença de Colaborador do CNCF.
2. Familiarize-se com o repositório de documentação e o gerador de site estático hugo.
3. Certifique-se de entender os processos básicos para melhorar o conteúdo e revisar alterações.

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.

Sua primeira contribuição

• Leia sobre visão geral para contribuição para saber mais sobre diferentes formas para você contribuir.
• Veja a lista de issues em kubernetes/website para identificar issues que sejam um bom ponto de partida.
• Abra um pull request usando o Github para documentações existentes e aprenda mais sobre resolver issues no Github.
• Leia sobre o guia de conteúdo e guias de estilo.
• Leia sobre tipos de conteúdo de páginas e shortcodes do Hugo.

Próximos passos

• Aprenda a trabalhar com um clone local de um repositório.
• Documente funcionalidades em uma release.
• Participe do SIG Docs, e se torne um membro ou revisor.
• Comece ou ajude com uma localização.

Se envolva com o SIG Docs

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:

• Entre em #sig-docs no slack do Kubernetes.
• Se inscreva na lista de email kubernetes-dig-docs, onde acontecem discussões e decisões oficiais são registradas.
• Participe do encontro semanal do SIG Docs. Os encontros são sempre anunciados no #sig-docs e adicionados ao calendário de eventos de comunidade do Kubernetes. Você precisa baixar o cliente do Zoom ou usar um telefone.

Outras formas de contribuir

• 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.
• Submeta um post de blog ou um caso de estudo.

1 - Contribuindo para os blogs do Kubernetes

Existem dois blogs oficiais do Kubernetes, e a CNCF também possui seu próprio blog, onde você pode encontrar informações sobre Kubernetes. No blog principal do Kubernetes, nós (o projeto Kubernetes) gostamos de publicar artigos com diferentes perspectivas e focos específicos, que tenham relação com o Kubernetes.

Com apenas algumas exceções especiais, publicamos conteúdos que não tenham sido submetidos ou publicados em nenhum outro lugar.

Leia as diretrizes do blog para saber mais sobre esse aspecto.

Blogs oficiais do Kubernetes

Blog principal

O blog principal do Kubernetes é utilizado pelo projeto para comunicar novas funcionalidades, relatórios da comunidade e quaisquer novidades relevantes para a comunidade Kubernetes. Isso inclui usuários finais e desenvolvedores. A maior parte do conteúdo do blog aborda coisas que acontecem no projeto principal, mas o Kubernetes, como projeto, também incentiva o envio de artigos sobre o que está acontecendo em outras partes do ecossistema!

Qualquer pessoa pode escrever um post para o blog e submetê-lo para publicação. Com apenas algumas exceções especiais, publicamos conteúdos que não tenham sido submetidos ou publicados em nenhum outro lugar.

Blog de contribuidores

O blog de contribuidores do Kubernetes é voltado para um público de pessoas que trabalham no Kubernetes, mais do que para pessoas que trabalham com Kubernetes. O projeto Kubernetes deliberadamente publica alguns artigos em ambos os blogs.

Qualquer pessoa pode escrever um post de blog e submetê-lo para revisão.

Atualizações e manutenção de artigos

O projeto Kubernetes não mantém artigos antigos publicados em seus blogs. Isso significa que qualquer artigo publicado há mais de um ano normalmente não será elegível para issues ou pull requests que solicitem alterações. Para evitar estabelecer precedentes, até mesmo pull requests tecnicamente corretos provavelmente serão rejeitados.

No entanto, existem exceções, como as seguintes:

• (atualizações em) artigos marcados como evergreen
• remoção ou correção de artigos que fornecem orientações que agora estão incorretas ou são perigosas de seguir
• correções para garantir que um artigo existente continue sendo renderizado corretamente

Para qualquer artigo com mais de um ano que não esteja marcado como evergreen, o site exibe automaticamente um aviso informando que o conteúdo pode estar desatualizado.

Artigos evergreen

Você pode marcar um artigo como evergreen definindo evergreen: true no front matter.

Nós só marcamos artigos de blog como mantidos (evergreen: true no front matter) se o projeto Kubernetes puder se comprometer a mantê-los indefinidamente. Alguns artigos realmente merecem isso; por exemplo, o time de comunicação de releases sempre marca os anúncios oficiais de lançamento como evergreen.

Próximos passos

• Conheça os blogs oficiais:
  • Blog do Kubernetes
  • Blog de contribuidores do Kubernetes
• Leia sobre revisão de pull requests de blogs

1.1 - Enviando artigos para blogs do Kubernetes

Existem dois blogs oficiais do Kubernetes, e a CNCF também possui seu próprio blog, onde você pode encontrar informações sobre Kubernetes. No blog principal do Kubernetes, nós (o projeto Kubernetes) gostamos de publicar artigos com diferentes perspectivas e focos específicos, que tenham relação com o Kubernetes.

Com apenas algumas exceções especiais, publicamos conteúdos que não tenham sido submetidos ou publicados em nenhum outro lugar.

Escrevendo para os blogs do Kubernetes

Como autor, você tem três caminhos diferentes para a publicação.

Caminho recomendado

A abordagem recomendada pelo projeto Kubernetes é: envie sua proposta de artigo entrando em contato com a equipe do blog. Você pode fazer isso pelo Slack do Kubernetes (#sig-docs-blog). Para artigos que você deseja publicar apenas no blog de contribuidores, também é possível enviar a ideia diretamente para o SIG ContribEx comms.

A menos que haja algum problema com o seu envio, a equipe do blog / SIG ContribEx irá conectar você com:

• um editor do blog
• seu parceiro de escrita (outro autor do blog)

Quando a equipe conecta você com outro autor, a ideia é que vocês se apoiem mutuamente, revisando os rascunhos um do outro. Você não precisa ser especialista no assunto; a maioria das pessoas que lerá o artigo também não será. Nós, a equipe de blog do Kubernetes, chamamos esse outro autor de parceiro de escrita.

O editor está lá para ajudar você ao longo da jornada, do rascunho até a publicação. Ele pode aprovar seu artigo diretamente para publicação ou pode organizar o processo de aprovação.

Leia escrever um artigo para blog para saber mais sobre o processo.

Começando com um pull request

O segundo caminho para escrever para nossos blogs é começar diretamente com um pull request no GitHub. A equipe do blog não recomenda essa abordagem; o GitHub é bastante útil para colaboração em código, mas não é ideal para escrita de textos longos.

É totalmente aceitável abrir um pull request inicial provisório com um commit vazio, e em seguida, trabalhar fora do GitHub antes de retornar ao PR inicial.

Assim como no caminho recomendado, tentaremos encontrar um parceiro de escrita e um editor do blog para você. Eles ajudarão você a preparar o artigo para publicação.

Processo de artigos pós lançamento de versão

O terceiro caminho é voltado para artigos sobre alterações no Kubernetes relacionadas a um lançamento de versão. Sempre que há um lançamento de versão, a equipe de Release Comms assume o controle do calendário de publicações do blog. Pessoas que adicionam funcionalidades a uma versão, ou que estão planejando outras alterações que o projeto precisa anunciar, podem entrar em contato com o Release Comms para que seu artigo seja planejado, redigido, revisado e eventualmente publicado.

Agendamento de artigos

Para o blog do Kubernetes, a equipe do blog geralmente programa publicações de artigos em dias úteis (Calendário Gregoriano, como utilizado nos EUA e em outros países). Quando é importante publicar em uma data específica que cai em um fim de semana, a equipe tenta acomodar essa necessidade.

A seção sobre escrever um artigo para blog explica o que fazer:

• inicialmente, não especifique uma data para o artigo
• porém, defina o artigo como rascunho (adicione draft: true no front matter)

Quando o bot Prow faz o merge do PR que você escreve, o artigo continua como rascunho e não é publicado. Um contribuidor do Kubernetes (você, seu parceiro de escrita ou alguém da equipe do blog) abre então um pequeno PR de acompanhamento marcando o artigo para publicação. Ao fazer o merge desse segundo PR, o artigo deixa de ser rascunho e passa a ser publicado automaticamente.

No dia em que o artigo está programado para ser publicado, a automação aciona o build do site e o artigo se torna visível.

Escrevendo um artigo

Após apresentar sua ideia, incentivamos você a usar o HackMD (um editor Markdown web) ou um documento do Google Docs para compartilhar uma versão editável do texto. Seu parceiro de escrita pode ler seu rascunho, e em seguida, fazer sugestões ou fornecer outros comentários, além de verificar se o conteúdo está alinhado com as diretrizes do blog.

Ao mesmo tempo, você normalmente será o parceiro de escrita dele e poderá seguir nosso guia sobre como apoiar o trabalho dele.

Etapas administrativas iniciais

Você deve assinar o CLA caso ainda não tenha feito isso. É recomendável iniciar esse processo cedo; se você estiver escrevendo como parte do seu trabalho, talvez precise verificar com a equipe jurídica ou com seu gestor para garantir que você está autorizado a assinar.

Rascunho inicial

A equipe do blog recomenda que você utilize o HackMD ou um documento do Google Docs, para preparar e compartilhar uma versão inicial do texto do artigo que possa ser editada em tempo real.

Seu parceiro de escrita pode comentar e / ou fornecer feedback sobre seu rascunho e irá (ou deveria) verificar se ele está de acordo com as diretrizes. Ao mesmo tempo, você será o parceiro de escrita dele e seguirá o guia que explica como você irá apoiar o trabalho dele.

Nesta fase, não se preocupe muito em acertar a formatação Markdown exatamente.

Se houver imagens, você pode colar versões bitmap para receber um feedback inicial. A equipe do blog pode ajudar você (mais tarde no processo) a preparar as ilustrações para a publicação final.

Markdown para publicação

Confira o formato Markdown de posts existentes no repositório do site no GitHub.

Se você ainda não estiver familiarizado, leia noções básicas de contribuição. Esta seção da página pressupõe que você não possui um clone local do seu fork e que você está trabalhando através da interface web do GitHub. Você precisa criar um fork remoto do repositório do site caso ainda não tenha.

No repositório do GitHub, clique no botão Criar novo arquivo. Copie o conteúdo existente do HackMD ou Google Docs e cole no editor. Mais detalhes sobre o conteúdo do arquivo serão fornecidos posteriormente nesta seção. Nomeie o arquivo de acordo com o título proposto para o post do blog, mas não inclua a data no nome do arquivo. Os revisores do blog trabalharão com você para definir o nome final do arquivo e a data que o artigo será publicado.

1. Ao salvar o arquivo, o GitHub irá guiá-lo através do processo de pull request.

2. Seu parceiro de escrita pode revisar o seu envio e trabalhar com você no feedback e detalhes finais. Um editor do blog aprova seu pull request para o merge, como um rascunho que ainda não foi agendado.

Front matter

O arquivo Markdown que você escrever deve usar o formato YAML do front matter do Hugo.

Aqui está um exemplo:

---
layout: blog
title: "Seu Título Aqui"
draft: true # será alterado para date: YYYY-MM-DD antes da publicação
slug: texto-em-minusculo-para-o-link-sem-espacos # opcional
author: >
  Autor-1 (Afiliação),
  Autor-2 (Afiliação),
  Autor-3 (Afiliação)  
---

• inicialmente, não especifique uma data para o artigo
• no entanto, defina o artigo como rascunho (adicione draft: true ao front matter do artigo)

Conteúdo do artigo

Certifique-se de usar títulos Markdown de segundo nível (## não #) como o nível de título mais alto no artigo. O title que você define no front matter se torna o título de primeiro nível da página.

Você deve seguir o guia de estilo, mas com as seguintes exceções:

• é aceitável que os autores escrevam um artigo em seu próprio estilo, desde que a maioria dos leitores compreenda o ponto que está sendo apresentado.
• é aceitável usar "nós" em um artigo do blog com múltiplos autores ou quando a introdução do artigo indica claramente que o autor está escrevendo em nome de um grupo específico. Como você notará nesta seção, embora nós evitemos usar "nós" em nossa documentação, é aceitável fazer exceções justificáveis.
• evitamos usar shortcodes do Kubernetes para chamadas (como {{< caution >}}). Isso porque as chamadas são direcionadas a leitores de documentação, e artigos de blog não são documentação.
• declarações sobre o futuro são aceitáveis, embora as usemos com cautela em anúncios oficiais em nome do Kubernetes.
• exemplos de código usados ​​em artigos de blog não precisam usar o shortcode {{< code_sample >}}, e muitas vezes é melhor (mais fácil de manter) que não o usem.

Diagramas e ilustrações

Para ilustrações, diagramas ou gráficos, utilize o shortcode figure sempre que possível. Você deve definir um atributo alt para acessibilidade.

Para ilustrações e diagramas técnicos, tente usar gráficos vetoriais. A equipe do blog recomenda SVG em vez de formatos de diagrama raster (bitmap / pixel) e também recomenda SVG em vez de Mermaid (você ainda pode capturar o código-fonte do Mermaid em um comentário). A preferência por SVG em vez de Mermaid se deve ao fato de que, quando os mantenedores atualizam o Mermaid ou fazem alterações na renderização do diagrama, eles podem não ter uma maneira fácil de entrar em contato com o autor original do artigo do blog para verificar se as alterações estão corretas.

O guia de diagramas destina-se à documentação do Kubernetes, não a artigos de blog. Ainda assim, é bom segui-lo, mas:

• não há necessidade de legendar os diagramas como Figura 1, Figura 2, etc.

A exigência de imagens escaláveis ​​(vetoriais) torna o processo mais difícil para pessoas menos familiarizadas com o assunto enviarem artigos; o Kubernetes SIG Docs continua buscando maneiras de reduzir essa barreira. Se você tiver ideias sobre como facilitar esse processo, por favor, ofereça-se para ajudar.

Para outras imagens (como fotos), a equipe do blog recomenda fortemente o uso de atributos alt. É aceitável usar um atributo alt vazio para os casos em que o software de acessibilidade não deve mencionar a imagem, mas essa é uma situação rara.

Mensagens de commit

No momento em que você marcar sua solicitação de pull request como pronta para revisão, cada mensagem de commit deve ser um breve resumo do trabalho que está sendo feito. A primeira mensagem de commit deve fazer sentido como uma descrição geral da postagem do blog.

Exemplos de uma boa mensagem de commit:

• Add blog post on the foo kubernetes feature
• blog: foobar announcement

Exemplos de mensagens ruins de commit:

• Placeholder commit for announcement about foo
• Add blog post
• asdf
• initial commit
• draft post

Squashing

Assim que você achar que o artigo está pronto para o merge, você deve fazer squash dos commits em seu pull request; se você não tiver certeza de como fazer isso, não hesite em pedir ajuda à equipe do blog.

1.2 - Diretrizes para o blog

Estas diretrizes abrangem o blog principal do Kubernetes e o blog de contribuidores do Kubernetes.

Todo o conteúdo do blog também deve aderir à política geral do guia de conteúdo.

Antes de você começar

Certifique-se de estar familiarizado com as seções de introdução de contribuindo para os blogs do Kubernetes, não apenas para aprender sobre os dois blogs oficiais e as diferenças entre eles, mas também para obter uma visão geral do processo.

Conteúdo original

O projeto Kubernetes aceita apenas conteúdo original, em inglês.

Essa restrição também se aplica à promoção de outros projetos da Linux Foundation e da CNCF. Muitos projetos da CNCF possuem seus próprios blogs. Estes geralmente são uma escolha melhor para publicações sobre um projeto específico, mesmo que esse projeto tenha sido criado especificamente para funcionar com Kubernetes (ou com Linux, etc.).

Conteúdo relevante

Os artigos devem conter conteúdo que se aplique de forma ampla à comunidade Kubernetes. Por exemplo, um envio deve focar no Kubernetes upstream, e não em configurações específicas de fornecedores. Para artigos enviados ao blog principal que não sejam artigos espelho, os hiperlinks no artigo devem normalmente direcionar para a documentação oficial do Kubernetes. Ao fazer referências externas, os links devem ser diversificados - por exemplo, um envio não deve conter apenas links para o blog de uma única empresa.

Os blogs oficiais do Kubernetes não são o local para propostas de fornecedores ou para artigos que promovam uma solução específica de fora do Kubernetes.

Às vezes, esse é um equilíbrio delicado. Você pode pedir orientação no Slack (#sig-docs-blog) para entender se um post é apropriado para o blog do Kubernetes e / ou para o blog de contribuidores - não hesite em entrar em contato.

O guia de conteúdo se aplica incondicionalmente a artigos de blog e aos PRs que os adicionam. Tenha em mente que algumas restrições no guia indicam que são relevantes apenas para a documentação; essas restrições marcadas não se aplicam a artigos do blog.

Localização

O site está localizado em vários idiomas; o inglês é o idioma base para todas as outras localizações. Mesmo que você fale outro idioma e fique feliz em fornecer uma localização, isso deve ser feito em um pull request separado (consulte idiomas por PR).

Direitos autorais e reutilização

Você deve escrever conteúdo original e deve ter permissão para licenciar esse conteúdo para a Cloud Native Computing Foundation (para que o projeto Kubernetes possa publicá-lo legalmente). Isso significa que não somente o plágio direto é proibido, mas também que você não pode escrever um artigo do blog se não tiver permissão para atender às condições de licenciamento de direitos autorais da CNCF (por exemplo, se o seu empregador tiver uma política de propriedade intelectual que restrinja o que você tem permissão para fazer).

A licença do blog permite o uso comercial do conteúdo para fins comerciais, mas não o contrário.

Grupos de interesse especial e grupos de trabalho

Tópicos relacionados à participação ou aos resultados das atividades dos SIGs do Kubernetes estão sempre no tópico (consulte o trabalho da Equipe de Comunicação de Contribuidores para suporte a esses posts).

O projeto normalmente espelha esses artigos em ambos os blogs.

Restrições nacionais sobre conteúdo

O site do Kubernetes possui uma licença de Provedor de Conteúdo de Internet (ICP) do governo da China. Embora seja improvável que isso seja um problema, o Kubernetes não pode publicar artigos que seriam bloqueados pela filtragem oficial de conteúdo da internet do governo chinês.

Diretrizes específicas para conteúdo de blog

Além do guia de estilo geral, os artigos de blog devem (não obrigatoriamente) se alinhar às recomendações de estilo específicas para blogs.

O restante desta página é uma orientação adicional; não são regras rígidas que os artigos devem seguir, mas os revisores provavelmente irão (e devem) solicitar ajustes em artigos que obviamente não estejam alinhados com as recomendações aqui descritas.

Diagramas e ilustrações

Para ilustrações - incluindo diagramas ou gráficos - utilize o shortcode figure sempre que possível. Você deve definir um atributo alt para acessibilidade.

Utilize imagens vetoriais para ilustrações, diagramas técnicos e gráficos similares; o formato SVG é fortemente recomendado.

Artigos que utilizam imagens rasterizadas para ilustrações são mais difíceis de manter e, em alguns casos, a equipe do blog pode solicitar que o autor revise o artigo antes da publicação.

Atemporalidade

Os posts do blog devem buscar ser à prova do futuro

• Dada a velocidade de desenvolvimento do projeto, o SIG Docs prefere uma escrita atemporal: conteúdo que não exija atualizações frequentes para se manter correto para o leitor.
• Pode ser melhor adicionar um tutorial ou atualizar a documentação oficial do que escrever uma visão geral de alto nível em um post do blog.
• Considere concentrar o conteúdo técnico mais extenso como uma "chamada para ação" do post do blog, e foque no problema ou no motivo pelo qual os leitores deveriam se importar.

Exemplos de conteúdo

Aqui estão alguns exemplos de conteúdo apropriado para o blog principal do Kubernetes:

• Anúncios sobre novos recursos do Kubernetes
• Explicações de como alcançar um determinado resultado usando Kubernetes; apresente uma abordagem de baixo esforço operacional para aprimorar uma implantação gradual.
• Comparações entre diferentes opções de software relacionadas a Kubernetes e cloud native. É aceitável incluir links para uma dessas opções, desde que você divulgue claramente qualquer conflito de interesse / relacionamento
• Relatos sobre problemas ou incidentes e como você os resolveu
• Artigos sobre a construção de plataformas cloud native para casos de uso específicos
• Sua opinião sobre pontos positivos ou negativos do Kubernetes
• Anúncios e notícias sobre componentes não centrais do Kubernetes, como a Gateway API
• Anúncios e atualizações pós-release
• Comunicados sobre vulnerabilidades de segurança importantes do Kubernetes
• Atualizações de projetos do Kubernetes
• Tutoriais e demonstrações
• Liderança de pensamento sobre Kubernetes e cloud native
• Os componentes do Kubernetes são propositalmente modulares, então textos sobre pontos de integração existentes como CNI e CSI são relevantes. Desde que você não escreva uma proposta de fornecedor, você também pode escrever sobre o que está do outro lado dessas integrações.

Aqui estão alguns exemplos de conteúdo apropriado para o blog de contribuidores do Kubernetes:

• Artigos sobre como testar suas alterações no código do Kubernetes
• Conteúdo sobre contribuições não relacionadas a código
• Discussões sobre funcionalidades em estágio alfa, cujo design ainda está em discussão
• Artigos do tipo “Conheça o time” sobre grupos de trabalho, SIGs, etc.
• Um guia sobre como escrever código seguro que fará parte do próprio Kubernetes
• Artigos sobre encontros de mantenedores e os resultados desses encontros

Exemplos de conteúdo que não será aceito

No entanto, o projeto não publicará:

• Propostas de fornecedores
• Um artigo que você já publicou em outro lugar, mesmo que apenas em seu próprio blog de baixo tráfego
• Grandes blocos de código-fonte de exemplo com apenas uma explicação mínima
• Atualizações sobre projetos externos que funcionam ou dependem do Kubernetes (esses devem ser publicados no blog do próprio projeto externo)
• Artigos sobre o uso do Kubernetes com um cloud provider específico
• Artigos que critiquem pessoas, grupos de pessoas ou empresas específicas
• Artigos que contêm erros técnicos importantes ou detalhes enganosos (por exemplo: se você recomendar desativar um importante controle de segurança em clusters de produção, porque isso pode ser inconveniente, é provável que o projeto Kubernetes rejeite o artigo)

2 - Revisando mudanças

Esta seção descreve como revisar conteúdo.

2.1 - Revisando pull requests

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.

Antes de revisar, é uma boa ideia:

• Ler o guia de conteúdo e o guia de estilo para que você possa deixar comentários esclarecedores.
• Entender as diferentes funções e responsabilidades na comunidade da documentação do Kubernetes.

Antes de começar

Antes de começar uma revisão:

• Leia o Código de Conduta da CNCF e certifique-se de cumpri-lo o tempo todo.
• Seja educado, atencioso e prestativo.
• 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.

Figura 1. Etapas do processo de revisão.

1. Acesse https://github.com/kubernetes/website/pulls. Você verá uma lista de todas as solicitações de pull requests abertos no site e na documentação do Kubernetes.

2. 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 label work in progress ainda não estão prontos para revisão.

3. 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.

4. Vá para a aba Files changed para iniciar sua revisão.

   1. Clique no símbolo + ao lado da linha que você deseja comentar.

   2. 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)

   3. 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)?
  • A página deve aparecer na lista em Documentação/Home?
• 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.

3 - 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.1 - Guia de Conteúdo da Documentação

Esta página contém orientações para a documentação do Kubernetes.

Se você tiver dúvidas sobre o que é permitido, junte-se ao canal #sig-docs no Slack do Kubernetes e pergunte!

Você pode se registrar no Slack do Kubernetes através do endereço https://slack.k8s.io/.

Para informações sobre como criar novo conteúdo para a documentação do Kubernetes, siga o guia de estilo.

Visão geral

O código-fonte para o website do Kubernetes, incluindo a documentação, é armazenado no repositório kubernetes/website.

Localizada dentro da pasta kubernetes/website/content/<codigo-do-idioma>/docs, a maior parte da documentação do Kubernetes é específica para o projeto Kubernetes.

O que é permitido

A documentação do Kubernetes permite conteúdo de projetos de terceiros somente quando:

• O conteúdo documenta software que existe no projeto Kubernetes
• O conteúdo documenta software que está fora do projeto, mas é necessário para o funcionamento do Kubernetes
• O conteúdo é canônico no kubernetes.io, ou está vinculado a conteúdo canônico em outro local

Conteúdo de terceiros

A documentação do Kubernetes contém exemplos aplicados de projetos no projeto Kubernetes — projetos que existem nas organizações kubernetes e kubernetes-sigs do GitHub.

Links para conteúdo ativo no projeto Kubernetes sempre são permitidos.

O Kubernetes requer alguns conteúdos de terceiros para funcionar. Exemplos incluem agentes de execução de contêiner (containerd, CRI-O, Docker), políticas de rede (plugins CNI), controladores Ingress, e sistemas de log.

A documentação pode conter vínculos com software de código aberto de terceiros fora do projeto Kubernetes somente quando estes projetos são necessários para o funcionamento do Kubernetes.

Conteúdo duplicado

Sempre que possível, a documentação do Kubernetes utiliza links para fontes canônicas de documentação ao invés de hospedar conteúdo duplicado.

Conteúdo duplicado requer o dobro de esforço (ou mais!) para manter e fica obsoleto mais rapidamente.

Mais informações

Se você tem dúvidas sobre o conteúdo permitido, junte-se ao canal #sig-docs do Slack do Kubernetes e faça sua pergunta!

Próximos passos

• Leia o guia de estilo.

3.2 - Guia de Estilo da Documentação

Esta página fornece orientações de estilo para escrita da documentação do Kubernetes. Estas são orientações, não regras. Utilize seu melhor julgamento e sinta-se livre para propor alterações neste documento através de um pull request.

Para informações adicionais sobre como criar novo conteúdo para a documentação do Kubernetes, leia o Guia de Conteúdo da Documentação.

Mudanças no guia de estilo são feitas pelo SIG Docs como um grupo. Para propor uma alteração ou adição, inclua o tópico na agenda de uma das reuniões futuras do SIG Docs, e participe da reunião para fazer parte da discussão.

Língua

A documentação do Kubernetes foi traduzida para diversas línguas (veja READMEs das Localizações).

A forma para localização de documentação em uma língua diferente está descrita em localizando a documentação do Kubernetes.

Padrões de formatação da documentação

Utilize upper camel case para objetos da API

Quando você se referir especificamente a interações com um objeto da API, utilize UpperCamelCase, também conhecido como Pascal case. Você poderá encontrar formatação de maiúsculas e minúsculas diferente, como por exemplo "configMap", na referência da API. Ao escrever documentação geral, prefira a utilização de upper camel case, chamando o objeto de "ConfigMap".

Quando você estiver discutindo um objeto da API, utilize a formatação de maiúsculas e minúsculas no estilo de sentença.

Os exemplos a seguir focam no estilo de formatação de maiúsculas e minúsculas. Para mais informações sobre como formatar nomes de objetos da API, revise a orientação relacionada no manual de estilo de código.

Utilize chevrons para espaços reservados

Utilize chevrons (< e >) para espaços reservados. Comunique ao leitor o que o espaço reservado significa. Por exemplo:

kubectl describe pod <nome-do-pod> -n <namespace>

Se o nome do namespace do Pod for default, você pode omitir o paramêtro '-n'.

Grife elementos de interface de usuário

Utilize itálico para definir ou introduzir novos termos

Utilize estilo de código para nomes de arquivos, diretórios e caminhos

Utilize o padrão internacional para pontuação dentro de aspas

Formatação de código embutido

Utilize estilo de código para código embutido, comandos e objetos da API

Para código embutido em um documento HTML, utilize a tag <code>. Em um documento Markdown, utilize os símbolos de crase (`).

Utilize estilo de código para nomes de campos de objetos e namespaces

Utilize estilo de código para ferramentas de linha de comando e nomes de componentes do Kubernetes

Iniciando sentenças com o nome de uma ferramenta de linha de comando ou de um componente

Utilize uma descrição geral no lugar de um nome de componente

Utilize estilo normal para valores de campos do tipo texto ou inteiro

Para valores de campos do tipo texto ou inteiro, utilize o estilo normal sem aspas.

Referindo-se a recursos da API do Kubernetes

Esta seção discorre sobre como referenciar recursos da API na documentação.

Clarificação sobre "recurso"

O Kubernetes utiliza a palavra "recurso" para se referir a recursos da API, como pod, deployment, e demais objetos. Também utilizamos "recurso" para falar de requisições e limites de recursos de CPU e memória. Sempre se refira a recursos da API como "recursos da API" para evitar confusão com recursos de CPU e memória.

Quando utilizar a terminologia da API do Kubernetes

As diferentes terminologias da API do Kubernetes são:

• Tipo de recurso: o nome utilizado na URL da API (como pods, namespaces)
• Recurso: uma instância única de um tipo de recurso (como pod, secret)
• Objeto: um recurso que serve como um "registro de intenção". Um objeto é um estado desejado para uma parte específica do seu cluster, que a camada de gerenciamento do Kubernetes tenta manter.

Sempre utilize "recurso" ou "objeto" ao se referir a um recurso da API em documentação. Por exemplo, utilize "um objeto Secret" ao invés de apenas "um Secret".

Nomes de recursos da API

Sempre formate nomes de recursos da API utilizando UpperCamelCase, também conhecido como PascalCase, e formatação de código.

Para código embutido em um documento HTML, utilize a tag <code>. Em um documento Markdown, utilize o sinal de crase (`).

Não separe um nome de objeto da API em palavras individuais. Por exemplo, escreva PodTemplateList no lugar de Pod Template List.

Para mais informações sobre o PascalCase e formatação de código, por favor revise as orientações relacionadas nas seções Utilize UpperCamelCase para objetos da API e Utilize estilo de código para código embutido, comandos e objetos da API.

Para mais informações sobre as terminologias da API do Kubernetes, por favor revise a orientação relacionada sobre terminologia da API do Kubernetes.

Formatação de fragmentos de código

Não inclua o prompt de comando

Separe os comandos de seus resultados

Verifique que o Pod está rodando no seu nó escolhido:

kubectl get pods --output=wide

A saída é semelhante a:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Exemplos de versionamento do Kubernetes

Exemplos de código e de configuração que incluem informação da versão devem ser consistentes com o texto que os acompanha.

Se a informação é específica para uma versão, a versão do Kubernetes deve ser definida na seção prerequisites dos modelos de página de tarefa ou de tutorial. Assim que a página for salva, a seção prerequisitos é exibida com o título Antes de você começar.

Para especificar uma versão do Kubernetes para uma página de tarefa ou de tutorial, inclua a chave min-kubernetes-server-version na seção de front matter.

Se o exemplo de YAML for um arquivo avulso, procure e revise os tópicos que o incluem como uma referência. Verifique que quaisquer tópicos que estejam utilizando o YAML avulso têm a informação de versão apropriada definida. Se um arquivo avulso YAML não for referenciado em nenhum tópico, considere apagá-lo ao invés de atualizá-lo.

Por exemplo, se você estiver escrevendo um tutorial que é relevante para a versão 1.8 do Kubernetes, o front matter do seu arquivo Markdown deve ser semelhante ao demonstrado abaixo:

---
title: <seu título de tutorial aqui>
min-kubernetes-server-version: v1.8
---

Nos exemplos de código e configuração, não inclua comentários sobre versões alternativas. Tenha o cuidado de não incluir afirmações incorretas em comentários nos seus exemplos, como por exemplo:

apiVersion: v1 # versões mais antigas usam...
kind: Pod
...

Kubernetes.io word list

Uma lista de termos específicos do Kubernetes para serem utilizados de forma consistente em todo o website.

Shortcodes

Os shortcodes do Hugo auxiliam na criação de diferentes níveis de atrativos retóricos. Nossa documentação suporta três diferentes shortcodes nessa categoria: Nota {{< note >}}, Cuidado {{< caution >}}, e Aviso {{< warning >}}.

1. Circunde o texto com uma abertura e um fechamento de shortcode.

2. Utilize a sintaxe abaixo para aplicar um estilo:

   {{< note >}}
   Não há necessidade de incluir um prefixo; o _shortcode_ fornece um automaticamente (Nota:, Cuidado:, etc.).
   {{< /note >}}
   

   A saída é semelhante a:

   Nota:

   O prefixo é gerado automaticamente com a seleção do tipo da tag.
   

Nota

Utilize {{< note >}} para destacar uma dica ou uma informação que pode ser útil para o leitor.

Por exemplo:

{{< note >}}
Você _ainda_ pode utilizar Markdown dentro destas seções de destaque.
{{< /note >}}

The output is:

Você pode utilizar o shortcode {{< note >}} em uma lista:

1. Utilize o _shortcode_ `note` em uma lista

1. Um segundo item em uma lista com um shortcode note embutido

    {{< note >}}
    _Shortcodes_ Aviso, Cuidado e Nota, embutidos em listas, devem ser indentados
    com quatro espaços. Veja mais em [Problemas comuns com _shortcodes_](#common-shortcode-issues).
    {{< /note >}}

1. Um terceiro item em uma lista

1. Um quarto item em uma lista

A saída é:

1. Utilize o shortcode note em uma lista

2. Um segundo item em uma lista com um shortcode note embutido

   Nota:

   _Shortcodes_ Aviso, Cuidado e Nota, quando embutidos em listas, devem ser
   indentados com quatro espaços. Veja mais em
   [Problemas comuns com _shortcodes_](#common-shortcode-issues).
   

3. Um terceiro item em uma lista

4. Um quarto item em uma lista

Cuidado

Utilize {{< caution >}} para chamar a atenção a informações importantes que podem evitar problemas.

Por exemplo:

{{< caution >}}
O estilo de chamada se aplica somente à linha diretamente acima da tag.
{{< /caution >}}

A saída é:

Aviso

Utilize {{< warning >}} para indicar perigo ou uma orientação que é crucial e deve ser seguida.

Por exemplo:

{{< warning >}}
Cuidado.
{{< /warning >}}

A saída é:

Problemas comuns com shortcodes

Listas ordenadas

Shortcodes interrompem listas numeradas a não ser que estejam indentados com quatro espaços antes da nota e da tag.

Por exemplo:

1. Preaqueça o forno a 350°F.

1. Prepare a massa e a coloque na assadeira.
   `{{< note >}}Unte a assadeira para melhores resultados.{{< /note >}}`

1. Asse por 20-25 minutos, ou até que ao testar com um palito este saia limpo.

A saída é:

1. Preaqueça o forno a 350°F.

2. Prepare a massa e a coloque na assadeira.

   Nota:

   Unte a assadeira para melhores resultados.

3. Asse por 20-25 minutos, ou até que ao testar com um palito este saia limpo.

Cláusulas include

Shortcodes dentro de cláusulas include fazem com que o build falhe. Você deve colocá-los no documento superior, antes e depois da cláusula include. Por exemplo:

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Elementos Markdown

Quebras de linha

Utilize uma única linha em branco para dividir conteúdo a nível de bloco como por exemplo cabeçalhos, listas, imagens, blocos de código, entre outros. A exceção são cabeçalhos de segundo nível, onde duas linhas em branco devem ser utilizadas. Cabeçalhos de segundo nível seguem o primeiro nível (ou o título) sem nenhum texto ou parágrafo precedente. Um espaçamento de duas linhas em branco auxilia a melhor visualização geral da estrutura do conteúdo em um editor de texto.

Cabeçalhos e títulos

Pessoas que acessam esta documentação podem estar fazendo uso de um leitor de tela ou outro tipo de tecnologia auxiliar. Leitores de tela são dispositivos de saída linear que falam de um item por vez em uma página. Se uma grande quantidade de conteúdo existe em uma página, você pode utilizar cabeçalhos para dar à página uma estrutura interna. Uma boa estrutura de página auxilia todos os leitores a navegar facilmente ou filtrar tópicos de interesse.

Parágrafos

Links

Listas

Agrupe em listas itens relacionados que devem aparecer em uma ordem específica, ou para indicar uma correlação entre vários itens. Quando um leitor de tela encontra uma lista, independentemente de ser uma lista ordenada ou não-ordenada, o leitor de tela anunciará ao usuário que há um grupo de itens em lista. O usuário pode então utilizar as teclas de seta para navegar para cima e para baixo entre os vários itens da lista. Links para navegação no website também podem ser marcados como itens de lista, pois nada mais são do que um grupo de links relacionados.

• Finalize cada item em uma lista com um ponto final se um ou mais itens na lista forem sentenças completas. Para consistência, normalmente todos os itens da lista devem ser sentenças completas, ou nenhum dos itens deve ser.

  Nota:

  Listas ordenadas que são parte de uma sentença introdutória incompleta podem
  ser mantidos em letras minúsculas e pontuados como se cada item fosse uma
  parte da sentença introdutória.
  

• Utilize o número um (1.) para listas ordenadas.

• Utilize (+), (*) ou (-) para listas não-ordenadas.

• Deixe uma linha em branco após cada lista.

• Indente listas aninhadas com quatro espaços (por exemplo, ⋅⋅⋅⋅).

• Itens de lista podem consistir de múltiplos parágrafos. Cada parágrafo subsequente em uma lista deve estar indentado em quatro espaços ou um caractere de tabulação.

Tabelas

O propósito semântico de uma tabela de dados é apresentar dados tabulados. Usuários que não fazem uso de leitores de tela podem inspecionar a tabela de forma visual rapidamente, mas um leitor de tela irá ler o conteúdo linha a linha. Uma legenda de tabela é utilizada para criar um título descritivo para uma tabela de dados. Tecnologias auxiliares utilizam o elemento HTML caption para identificar o conteúdo da tabela para o usuário dentro da estrutura da página.

• Adicione legendas às suas tabelas utilizando os shortcodes do Hugo para tabelas.

Melhores práticas de conteúdo

Esta seção contém melhores práticas sugeridas para conteúdo claro, conciso e consistente.

Utilize o tempo presente

Exceção: utilize o tempo futuro ou pretérito quando necessário para comunicar o significado correto.

Utilize voz ativa

Exceção: utilize a voz passiva se a voz ativa resultar em uma construção estranha.

Utilize linguagem simples e direta

Utilize linguagem simples e direta. Evite utilizar frases ou expressões desnecessárias, como "por favor".

Dirija-se ao leitor utilizando "você"

Evite frases em Latim

Prefira termos em inglês no lugar de abreviações em Latim.

Exceção: utilize "etc." para et cetera.

Padrões a evitar

Evite utilizar "nós"

O uso de "nós" em uma sentença pode ser confuso, pois o leitor pode não saber se é parte do "nós" que você está descrevendo.

Evite jargões e expressões idiomáticas

Alguns leitores falam inglês como segunda língua. Evite jargões e expressões idiomáticas para auxiliar na compreensão.

Evite afirmações sobre o futuro

Evite fazer promessas ou dar dicas sobre o futuro. Se você precisa falar sobre uma funcionalidade em estado alfa, coloque o texto sob um cabeçalho que classifique a informação em estado alfa.

Uma exceção a esta regra é a documentação sobre descontinuações que serão convertidas em remoções em uma versão futura. Um exemplo deste tipo de documentação é o Guia de migração de APIs descontinuadas.

Evite afirmações que ficarão desatualizadas em breve

Evite palavras como "atualmente" e "novo". Uma funcionalidade que é nova hoje pode não ser mais considerada nova em alguns meses.

Evite palavras que assumem um nível específico de conhecimento

Evite palavras como "apenas", "simplesmente", "fácil", "facilmente" ou "simples". Estas palavras não agregam valor.

Próximos passos

• Aprenda sobre como escrever um novo tópico.
• Aprenda sobre como utilizar modelos de páginas.
• Aprenda sobre como criar um pull request.

4 - Visualizando Analytics do Site

Esta página contém informações sobre o painel de analytics do kubernetes.io.

Ver o painel.

Este painel foi criado usando o Google Looker Studio e mostra informações coletadas no kubernetes.io usando o Google Analytics 4 desde agosto de 2022.

Usando o painel

Por padrão, o painel mostra todas as análises coletadas nos últimos 30 dias. Use o seletor de data para ver dados de um intervalo de datas diferente. Outras opções de filtragem permitem que você visualize dados com base na localização do usuário, no dispositivo usado para acessar o site, na tradução dos documentos usados ​​e muito mais.

Se você identificar algum problema com este painel ou quiser solicitar alguma melhoria, abra um problema no repositório.

5 - Contribuir com a documentação do Kubernetes em Português Brasileiro

Olá!

Esta página contém informações sobre o processo de localização em português (Brasil), desde o processo de contribuição até um dicionário de termos com as respectivas traduções.

Antes de você começar

Familiarize-se com o processo de contribuição do Projeto Kubernetes no GitHub

• Leia o guia da pessoa contribuidora do Kubernetes.
• Leia os guias de conteúdo e de estilo do website do Kubernetes.
• Familiarize-se com o código de conduta do Projeto Kubernetes.
• (Opcional) Abra um Pull Request de teste no repositório contributor-playground.

Prepare seu ambiente de desenvolvimento

• Instale as ferramentas necessárias.
• Crie um fork do repositório kubernetes/website na sua conta do GitHub (instruções).
• Clone o fork do repositório em sua máquina local (instruções).
• (Opcional, recomendado) Verifique que você consegue rodar a visualização prévia do website em sua máquina local seguindo as instruções do repositório.

Passo a passo para contribuição

1. Escolha uma página que deseja localizar.
2. Verifique se já existe uma issue no repositório (kubernetes/website) aberta para a página que escolheu.
   • Caso não exista, crie uma nova issue com título no formato [pt-br] Localize <caminho>. Cole o link da issue no canal #kubernetes-docs-pt do Slack do Kubernetes para que um dos mantenedores possa fazer a triagem e adicionar os labels corretos.
3. Crie uma branch no seu fork e faça a localização da página.
4. Execute o check de links quebrados (os detalhes de como executar estão nessa página).
5. Abra o Pull Request. Caso ainda não tenha assinado o CLA, haverá instruções no Pull Request.
6. Verifique se as checagens no Pull Requests não estão quebradas e se foi gerado um preview da sua localização.

   Nota:

   A geração da pré-visualização da página é uma verificação obrigatória do Pull Request. Pull Requests que não passarem nesta verificação não podem ser mesclados.
7. Por fim, recomendamos que envie o pull request no canal do slack do time #kubernetes-docs-pt.

Checagem de links quebrados

Para garantir que os links referenciados na página que localizou não estão quebrados, você pode executar um script de checagem de links quebrados.
Dentro do seu fork local do repositório, executar:

scripts/linkchecker.py -f content/pt-br/<caminho-da-pagina>

onde content/pt-br/<caminho-da-pagina> é o caminho da página que está sendo localizada.

Dicionário de termos com tradução

Este dicionário de termos contém traduções que foram previamente utilizadas em páginas localizadas. Caso não se encaixe no contexto por algum motivo, sugerimos trazer para discussão no canal #kubernetes-docs-pt do Slack antes do Pull Request ser aberto.

Dicionário de termos não traduzidos

Via de regra, nomes de APIs do Kubernetes permanecem no original utilizando camel case conforme o nome da API. Alguns exemplos (lista não-exaustiva):

• ClusterRole
• ConfigMap
• Deployment
• Pod
• Service

A tabela abaixo contém termos que não foram previamente traduzidos em localizações já concluídas.

Perguntas frequentes

Qual título devo usar quando abrir o Pull Request?

Recomendamos usar o formato [pt-br] Update/Add <caminho do arquivo>.

Posso abrir um Pull Request traduzindo mais de uma página de documentação?

Sempre dê preferência por abrir um Pull Request por página, dessa forma facilita a revisão e o acompanhamento do trabalho.

Tenho dúvidas nos termos, preciso abrir o Pull Request e esperar alguém revisar?

Não, pode mandar a dúvida no canal do slack (#kubernetes-docs-pt) que vamos ajudar com a dúvida.

Abri um Pull Request mas ainda não teve revisão, o que fazer?

É importante lembrar que as pessoas revisoras são voluntárias, então em alguns casos pode demorar um pouco. O que recomendamos nesses casos é enviar uma mensagem no canal do slack com o link do Pull Request, assim podemos verificar o que pode ter acontecido.

Ficou alguma dúvida que não foi respondida nessa página?
Fale com a gente canal no slack do Kubernetes #kubernetes-docs-pt.