Guia de estilo

A abordagem de estilo do GitHub Docs

• Nosso guia de estilo visa a simplicidade. As diretrizes devem ser fáceis de serem aplicadas a uma variedade de cenários.
• As decisões não se tratam do que é certo ou do que é errado segundo as regras gramaticais ou o guia de estilo, mas do que é melhor para os usuários. Somos flexíveis e estamos abertos a alterações e, ao mesmo tempo, mantendo a consistência.
• Para escalar o guia de estilo à medida que nossa equipe e os conjuntos de documentação crescem e criar um conteúdo significativo e de alta qualidade que atenda aos usuários, concentramos nossa atenção em cenários de alto impacto e de alto valor, em vez de tentar abranger por completo todas as perguntas sobre estilo.
• Consistência e correção gramatical são importantes, mas não tão importantes quanto clareza e significado.
• Ao tomar uma decisão sobre estilo ou estrutura, consideramos o fluxo de informações dentro da unidade de conteúdo e o contexto das informações.
• Quando uma pergunta específica para auxiliar a documentação não é abordada pelo guia de estilo, pensamos nisso usando esses princípios e, em seguida, tomamos uma decisão. Se um revisor perguntar sobre isso, estaremos preparados para discutir a decisão.

Eventos do log de auditoria

Estão documentados todos os eventos que podem aparecer nos logs de auditoria para cada tipo de conta: usuário, organização e empresa.

•         [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events)
  

•         [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization)
  

•         [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise) 
  

Ao escrever a descrição de um evento do log de auditoria, descreva-o de maneira que se aplique a todas as versões, usando tempo passado e voz passiva. Não comece a frase com frases já implícitas no contexto do artigo, como "Iniciado por".

•         **Uso:** A visibilidade de um repositório foi alterada.
  

•         **Usar:** a verificação do segredo foi habilitado para todos os novos repositórios.
  

•         **Evitar**: o proprietário de uma organização desabilitou um requisito de autenticação de dois fatores para a organização.
  

•         **Evitar:** Acionado quando um usuário atualiza os repositórios aos quais um codespace pode acessar.
  

Alertas

Os alertas enfatizam informações em um artigo que são de especial importância e justificam a quebra do fluxo de informações.

Use alertas com moderação. Não use alertas consecutivos ou mais de um alerta por seção.

Os alertas devem ser concisos. Se as informações consistirem em mais de duas frases ou exigirem uma lista ordenada ou não ordenada, considere colocá-las em um título de seção.

Tipos de alerta

Usamos cinco tipos de alertas: Observação, Dica, Importante, Aviso e Cuidado.

Observação

Fornece contexto adicional que os usuários podem precisar levar em conta. As tarefas podem ser realizadas sem as informações nos alertas de notas, mas alguns usuários, em alguns contextos, podem aproveitar a nota.

As notas são particularmente úteis para comunicar informações entre parênteses que não são centrais para o processo que está sendo descrito:

• Advertências que podem afetar o resultado final de um processo, como configurações específicas do usuário.
• Produtos e recursos que estão sujeitos a alterações na disponibilidade, como aqueles em versão prévia pública ou encerrando.

Por exemplo, Avaliar alertas da verificação de segredo usa uma nota para informar aos usuários que os metadados para tokens GitHub estão atualmente em versão prévia pública.

Dica

Recomendações, melhores práticas ou dicas de produtos. As dicas contêm informações não essenciais que os usuários podem seguir a seu critério. Particularmente útil em artigos destinados a novos usuários.

Por exemplo, Personalizar seu perfil usa um alerta de dica para ajudar os usuários a entender o que esperar quando estiverem @mention em uma organização.

Importante

Realça as principais informações que os usuários precisam saber para atingir sua meta.

Aviso

Realça os riscos potenciais dos quais um usuário deve estar ciente antes de iniciar ou continuar com uma tarefa.

Os alertas de aviso são especificamente relevantes para processos que ocorrem fora da interface do usuário do GitHub, como na linha de comando ou via API.

Por exemplo, Sobre autoridades certificadas de SSH inclui instruções para a linha de comando e usa um alerta de aviso para informar os usuários que, depois de emitidos, os certificados não poderão ser revogados:

Cuidado

Alerta os usuários sobre ações perigosas ou destrutivas que exigem extrema cautela antes da execução, especialmente quando há um risco de segurança ou potencial de perda de dados.

Os alertas de cuidado, no geral, só serão necessários ao descrever processos que ocorrem fora da interface do usuário do GitHub, como na linha de comando ou via API.

Formatação dos alertas

Usamos formatação e cores padrão para diferentes tipos de alertas nos conjuntos de documentação.

Os alertas são gerados com Markdown.

Observação:

> [!NOTE]
> Keep this in mind.

Dica:

> [!TIP]
> Here's a suggestion.

Aviso:

> [!WARNING]
> Be careful.

Cuidado:

> [!CAUTION]
> Be extremely careful.

A sintaxe líquida dos alertas ainda é compatível e pode aparecer em artigos mais antigos, mas não deve ser usada para alertas novos.

Para saber mais sobre como formatar alertas, consulte "Alertas" em Como usar Markdown e Liquid no GitHub Docs.

Chamada para ação (CTA)

Uma CTA é um link ou um botão que solicita que os usuários realizem a etapa seguinte do percurso. Ele levará o usuário para um local diferente.

O principal componente de uma CTA é que ela ajuda o usuário a fazer o que estava tentando fazer, levando-o à próxima etapa ou a um produto ou recurso necessário.

Ao considerar quando usar uma CTA, faça as seguintes perguntas:

• Há uma próxima etapa lógica ou necessária para o usuário? Podem ser as próximas informações necessárias ou um recurso que o ajudaria a realizar sua tarefa.
• Há uma necessidade de negócios que demanda enviar o usuário para esse lugar?

Só devemos usar uma CTA quando a resposta para ambas as perguntas é sim.

Como uma CTA é diferente de um link?

Uma CTA é uma instrução explícita para o usuário agir imediatamente, como “Experimente o Copilot gratuitamente” ou “Crie seu repositório”. Uma CTA em nossa documentação só deve levar as pessoas a um domínio pertencente ao GitHub.

Por exemplo, a CTA em Configurando uma avaliação do GitHub Enterprise Cloud leva a uma página de vendas da empresa no GitHub.com.

Criando CTAs

Para criar uma URL de CTA válida com os parâmetros corretos, use o script do criador de CTA no seu repositório de documentos:

npm run cta-builder

O script orientará você por meio de um processo interativo para:

• Selecione o produto apropriado GitHub (ref_product)
  • Use github como padrão quando o link não for específico para um determinado recurso ou produto
• Escolha o tipo de ação (ref_type)
• Especificar o estilo de formatação (ref_style)
• Opcionalmente, selecione um plano específico (ref_plan)

O script fornece todas as opções disponíveis para cada parâmetro e gera uma URL CTA completa e válida no final. Use essa ferramenta para garantir que você esteja usando valores atuais e aprovados para parâmetros CTA.

Por exemplo, o script pode gerar uma URL como:

https://github.com/account/enterprises/new?ref_product=ghec&ref_type=trial&ref_style=button&ref_plan=enterprise

Code

Blocos de códigos

Mantenha as linhas em exemplos de código em cerca de 60 caracteres, para evitar que os leitores precisem rolar a página horizontalmente no bloco de código. Localize o texto explicativo antes do bloco de código, em vez de usar comentários dentro do bloco de código. Consulte Como usar Markdown e Liquid no GitHub Docs para saber mais sobre a sintaxe e a formatação dos blocos de código.

Dentro de blocos de código:

• Especifique a linguagem do exemplo após o primeiro limite de código. Para ver uma lista de todas as linguagens compatíveis, confira Code languages no repositório github/docs.

• Não use HTML para definir o estilo ou a marcação em um bloco de código.

• Defina o estilo de todos os espaços reservados que as pessoas precisam substituir por valores próprios em letras maiúsculas. * Usar:git checkout -b BRANCH-NAME * Evite:git checkout -b <branch-name>

• Não use prompt de comando como $ antes do comando. Esses prompts tornam difícil para os leitores copiar e colar o comando.

  • Se você mostrar um comando e a saída do comando, comente a saída no exemplo.

  •       **Use:**
    

    command
    # output
    

  •       **Evitar**:
    

    $ command
    output
    

• Se o exemplo de código incluir um { ou um } que deve ser renderizado, coloque essa seção entre {% raw %}{% endraw %} para desabilitar o processamento do Liquid dessa seção. * Use:

    GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
    

  •       **Evitar**:
    

    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    

• Se o seu exemplo de código incluir conteúdo que deva ser analisado, envolva essa seção em tags <pre>``</pre> para analisar, em vez de escapar o conteúdo da seção.

Comandos

Use blocos de código embutidos para referenciar nomes de comandos curtos. * Use: para verificar o status de um cluster em execução, use o comando ghe-cluster-status.

Use blocos de comando para comandos mais longos ou mais complexos. * Uso: Para habilitar o modo de manutenção de acordo com a janela agendada, conecte-se ao shell administrativo de qualquer nó do cluster e execute:

ghe-cluster-maintenance -s

Não inclua prompts de comando como $. Evite links embutidos em nomes de comandos.

Saídas

Se você mostrar a saída de um comando, comente a saída no exemplo para que as pessoas possam copiar e colar o comando e executá-lo sem modificação.

•         **Use:**
  

  git lfs install
  # Git LFS initialized.
  

•         **Evitar**:
  

  $ git lfs install
  > Git LFS initialized.
  

Exemplos

Quando os exemplos de código referenciarem um arquivo maior, mostre a seção relevante do arquivo, de modo que os usuários entendam como editar o respectivo código no contexto. * Use:

on:
  schedule:
    - cron:  "40 19 * * *"

•         **Evitar**:
  

schedule:
  - cron:  "40 19 * * *"

Nomes de arquivo e nomes de diretório

Use backticks para formatar referências a nomes de arquivo e nomes de diretório em uma fonte monoespaçada. Se, em geral, um tipo de arquivo seguir uma convenção específica de uso de maiúsculas, como todas as letras em maiúsculas em arquivos LEIAME, use a convenção estabelecida.

•         **Use:** no arquivo `README.md`, adicione informações sobre o repositório.
  

•         **Use:** no diretório `.github/workflows/`, crie o arquivo `example-workflow.yml`.
  

•         **Evite:** no diretório _.github/workflows/_, crie o arquivo `example-workflow.yml`.
  

•         **Evite:** exclua o arquivo **example.js**.
  

Recuo

Em exemplos YAML, como ações e arquivos de fluxo de trabalho, use dois espaços para recuar as linhas em listas aninhadas e sequências de bloco.

•         **Use:**
  

    steps:
      - uses: actions/checkout@v5
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}

Para recuar reutilizáveis, confira data/reusables/README.md.

Fluxos de trabalho agendados

As execuções de fluxo de trabalho são atrasadas quando muitos fluxos de trabalho são executados de uma só vez. Como muitos usuários copiam o código do GitHub Docs, devemos usar exemplos que orientam os usuários para longe dos horários congestionados.

• Não use exemplos que são executados de hora em hora, pois esses são os horários mais congestionados.
• Não use exemplos que são executados com mais frequência do que o necessário. Por exemplo, em vez da execução a cada cinco minutos, considere se faz sentido para o exemplo ser executado a cada 30 minutos.
• Use um horário diferente para cada exemplo.

Ênfase

Use negrito para enfatizar palavras ou partes de uma frase. Use ênfase com moderação (não mais do que cinco palavras contíguas) e lembre-se de que é um auxílio visual para escaneamento para usuários com visão.

• Não coloque em negrito palavras que tenham outra formatação aplicada, como letras maiúsculas para texto de espaço reservado.
• Para acessibilidade, não use negrito como a única maneira de transmitir significado ou ênfase.

Por exemplo:

•         **Use:** contas de usuário gerenciadas **não podem criar conteúdo público** ou colaborar fora da empresa.
  

•         **Evite:** ao lado de _**Título**_, adicione um rótulo descritivo para a nova chave.
  

Mensagens de erro

Ao incluir o texto de uma mensagem de erro de um produto ou interface do GitHub em um artigo, formate o texto conforme a interface onde a mensagem aparece.

• Se a mensagem aparecer na interface da Web do GitHub ou em um aplicativo cliente gráfico como GitHub Desktop ou GitHub Mobile, trate a mensagem como outro texto na interface do usuário. Para saber mais, confira Texto da interface do usuário.

• Se a mensagem aparecer em uma interface de linha de comando, em uma saída de log ou em uma resposta de uma API, reproduza o texto exatamente e use acentos graves para formatar a mensagem usando uma fonte monoespaçada.

Conteúdo em vencimento

Em geral, não documente o conteúdo que irá expirar. Qualquer pessoa que visite GitHub Docs deve ter certeza de que as informações são precisas e atualizadas.

Se você precisar documentar o conteúdo que sabe que vai expirar, poderá usar o linter de conteúdo para marcar e acompanhar a data de expiração do conteúdo. Isso sinalizará o conteúdo como desatualizado e evitará o rastreamento de datas de expiração fora do conteúdo em si. Consulte Usando o linter de conteúdo para obter informações sobre como formatar tags de conteúdo que expira.

Notas de rodapé

Evite usar notas de rodapé sempre que possível. Cogite, em vez disso, se você consegue usar um alerta ou apresentar as informações de outra maneira. Veja alguns exemplos de alternativas às notas de rodapé em NICE.org.uk.

Se precisar usar notas de rodapé, use notas de rodapé nativas do Markdown ([^1]). Os marcadores das notas de rodapé terão um hiperlink para a referência correspondente, que será listada na parte inferior da página com um link de retorno para o marcador.

Observe que, independentemente do identificador usado (letras, palavras), as notas de rodapé serão renderizadas como números sequenciais.

          [^1]: Not to be confused with Davy Jones of The Monkees

          [^2]: Also humans

| | Mona | Ursula | Paul | Davy Jones[^1] |
|---|---|---|---|---|
|Favorite pastime| Shipping code | Tricking mermaids[^2] | Predicting sports | Haunting seafarers |
|Uses powers for good| Yes | No | Yes | No |
[^1]: Not to be confused with Davy Jones of The Monkees
[^2]: Also humans

Cabeçalhos

Os cabeçalhos precisam descrever adequadamente o conteúdo abaixo deles. Os cabeçalhos podem seguir as diretrizes para escrever títulos ou podem ser escritos como perguntas. Use capitalização de frases nos cabeçalhos.

Se um artigo tiver cabeçalhos, eles precisarão começar com um cabeçalho de nível H2. Você pode usar cabeçalhos de nível H3 e H4 para organizar ainda mais o conteúdo em grupos relacionados, mas não pode ignorar os níveis de cabeçalho. Deve haver conteúdo de texto entre um cabeçalho e um subtítulo, como uma introdução. * Use:

## HEADER (H2)

TEXT

### SUBHEADER (H3)

TEXT

#### SUBHEADER (H4)

TEXT

•         **Evitar**:
  

  ## HEADER (H2)
  
  #### SUBHEADER (H4)
  

Cada cabeçalho no mesmo nível de uma página precisa ser exclusivo.

•         **Use:**
  

  ## Examples  (H2)
  
  TEXT
  
  ### Prompts for writing code (H3)
  
  TEXT
  
  ### Prompts for writing tests (H3)
  
  TEXT
  

•         **Use:**
  

  ## Prompts for writing code (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  
  ## Prompts for writing tests (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  

•         **Evitar**:
  

  ## Example prompts (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  

Imagens

Usamos imagens estáticas, incluindo capturas de tela, diagramas e grafos, em todos os documentos para complementar informações textuais.

Não use GIFs animados na documentação.

Texto alternativo

Cada imagem precisa incluir um texto Alt que forneça um equivalente textual das informações visuais.

• Expresse a ideia principal ou o significado da imagem, em vez de descrevê-la literalmente.
• Use de 40 a 150 caracteres.
• Termine com um sinal de pontuação. Em geral, isso deve ser um ponto final, a menos que o texto Alt descreva uma imagem de texto que termine com outro sinal de pontuação, como um ponto de interrogação ou um ponto de exclamação.
• Não comece com "Imagem…" nem "Gráfico…". Os leitores de tela dizem isso automaticamente.
• Comece com o tipo de gráfico: "Captura de tela de…" ou "Diagrama que mostra…"
• Siga a linguagem padrão usada para descrever os elementos de interface do usuário no texto do artigo.
• Coloque os títulos com várias palavras, como nomes de itens de menu, entre aspas duplas ("").
• Se uma área da imagem estiver visualmente realçada, descreva como ela está. Isso permite que os usuários de leitores de tela entendam e descrevam a um amigo/colega com deficiência visual o que deve ser procurado do ponto de vista da linguagem visual.

Texto Alt para capturas de tela

O texto Alt fornece uma breve descrição do conteúdo de uma captura de tela para beneficiar as pessoas que não podem vê-lo.

• O texto Alt só precisa incluir os elementos mais relevantes de uma imagem, não todos os detalhes.
• O texto Alt não se destina a fornecer instruções de uso da interface do GitHub. Elas devem ser incluídas no texto do artigo complementar.

Formato

Captura de tela do Product name + UI element exibido. O UI element + state of the element/controls e o respectivo keyboard shortcut XYZ são realçados em laranja escuro.

• Em Product name, use o nome do produto ou do recurso do GitHub, como "GitHub Actions" ou repositório "GitHub", em vez de apenas "GitHub".
• Use uma variável para a palavra GitHub como fazemos em texto corrido: {% data variables.product.prodname_dotcom %}
• Descreva os elementos de interface do usuário de maneira consistente com a documentação escrita.
• Seja flexível com a ordem de palavras quando necessário para maior clareza.
  • Por exemplo, escreva "Captura de tela do menu Depurar no Visual Studio Code…" em vez de "Captura de tela do menu Depuração do Visual Studio Code…", para evitar vários substantivos em uma linha.

Exemplos

Captura de tela dos autores de commits do GitHub por tabela do repositório. O ícone de kebab horizontal e o botão "Baixar relatório CSV" são destacados em laranja escuro.

Captura de tela das opções de arquivo em um repositório GitHub. Um botão com uma seta indicando um menu suspenso, rotulado "Código", está contornado em laranja escuro.

Texto Alt para diagramas e grafos

Explique as informações transmitidas no diagrama ou no grafo em um texto na página.

Use o texto Alt para expressar a ideia principal da imagem, sem duplicar o texto da página da Web.

Exemplo

Diagrama que mostra um processo de cinco etapas pelo qual um executor do GitHub Actions pode ser adicionado automaticamente às classes nomeadas de executores e solicitado por trabalhos específicos.

Por exemplo, confira a explicação que acompanha esse diagrama na documentação do Actions.

Texto Alt para imagens de interfaces de linha de comando

Não use capturas de tela de interfaces de linha de comando para transmitir comandos e a respectiva saída. Em vez disso, forneça diretamente os comandos que um usuário deve usar. Para saber mais, confira a seção Comandos do guia de estilo.

Ao usar uma captura de tela de uma interface de linha de comando para mostrar os elementos de interface do usuário, siga as diretrizes de texto Alt padrão para capturas de tela.

Nomes de arquivo para imagens

Seja descritivo ao nomear arquivos de imagem: inclua o nome, a ação e o elemento de interface do usuário no nome do arquivo. Espelhe a linguagem do produto. Use maiúsculas e minúsculas no estilo kebab. Não use condicionais do Liquid em nomes de arquivo. Se estiver substituindo uma imagem, use o nome do arquivo exato. * Usar:data-pack-purchase-button.png * Evite:purchase_button.png * Evite:purchase-button-for-admins.png

Capturas de tela

Para saber mais sobre como criar imagens e fazer o controle de versão delas, confira Como criar e atualizar capturas de tela.

Diagramas

Para saber mais sobre a criação de diagramas, confira Criando diagramas para o GitHub Docs.

Linguagem inclusiva

Como o lar da maior comunidade de desenvolvedores do mundo, o GitHub está comprometido em promover a diversidade e a inclusão em todos os aspectos do que fazemos. Toda a nossa documentação é inclusiva e respeitosa com o nosso público-alvo, que consiste em pessoas em circunstâncias amplamente variadas de todo o planeta. Quando escrevemos nossa documentação, usamos palavras inclusivas, antirracistas e acessíveis.

Palavras individuais podem ser pequenas, mas juntas podem criar comunidade, sentimento de pertencimento e equidade. Seja empático em todas as escolhas de palavras e estilos. Seja preciso ao se referir a pessoas e comunidades.

Recursos sobre linguagem inclusiva

O Guia de Estilo da Microsoft oferece recursos sobre comunicação sem preconceitos, termos de acessibilidade e como escrever para todas as habilidades: * Comunicação livre de desvio * Como escrever para todas as habilidades * Termos de acessibilidade

Mais recursos para aprender sobre linguagem e estilo inclusivos e acessíveis:

• Guia de Estilo de Conteúdo da MailChimp: * Como escrever sobre pessoas * Como escrever para acessibilidade

•         [Diretrizes de legibilidade](https://readabilityguidelines.co.uk/)
  

•         [Guia de Estilo Consciente](https://consciousstyleguide.com/)
  

Atalhos do teclado

Para apresentar atalhos de teclado, siga o Guia de Estilo da Microsoft, com exceção das seguintes diferenças:

• Use a tag HTML <kbd> para cada tecla individual.

  •       **Usar:**`<kbd>Command</kbd>+<kbd>B</kbd>`
    

  •       **Evite:**`Command+B`
    

• Use palavras completas em vez de símbolos para teclas modificadoras da Apple.

  •       **Usar:**`Command`
    

  •       **Evite:**`⌘`
    

• Use símbolos para teclas de caracteres especiais, não palavras completas.

  •       **Use:**`.`, `,` e `→`.
    

  •       **Evite:**`Period`, `Comma` e `Right arrow`.
    

Destaques de uso

Aqui, abaixo alguns realces de uso de como apresentamos os atalhos de teclado em nossa documentação:

• A sintaxe básica é mostrar as teclas com + entre combinações de teclas, sem espaços.

  •       **Use:**`<kbd>Command</kbd>+<kbd>B</kbd>`, que é renderizado como <kbd>Command</kbd>+<kbd>B</kbd>.
    

  •       **Evite:**`<kbd>Command</kbd> + <kbd>B</kbd>` ou `<kbd>Command + B</kbd>` que são renderizados como <kbd>Command</kbd> + <kbd>B</kbd> ou <kbd>Command + B</kbd>.
    

• Sempre use maiúsculas para a primeira letra das teclas de letras para referências gerais e atalhos de teclado.

  •       **Use:**<kbd>Command</kbd>+<kbd>B</kbd>
    

  •       **Evite:**<kbd>Comando</kbd>+<kbd>b</kbd>.
    

• Utilize as teclas modificadoras corretas para cada um dos sistemas operacionais.

          **Observação:** o Windows e o Linux têm o <kbd>CTRL</kbd> abreviado, enquanto no Mac, ele é escrito na íntegra: <kbd>Control</kbd>.
  

  • Para Windows e Linux:

    •     **Use:**<kbd>CTRL</kbd>, <kbd>Alt</kbd>.
      

    •     **Evite:**<kbd>Controle</kbd>
      

  • Para Mac:

    •     **Use:**<kbd>Command</kbd>, <kbd>Option</kbd>, <kbd>Control</kbd>.
      

    •     **Evite:**<kbd>Cmd</kbd>, <kbd>⌘</kbd>, <kbd>Opt</kbd>, <kbd>⌥</kbd>, <kbd>Ctrl</kbd>, <kbd>⌃</kbd>
      

• Não confunda as combinações de teclas com as teclas em uma sequência.

  •       <kbd>Command</kbd>+<kbd>B</kbd> indica que o usuário deve manter pressionada a tecla <kbd>Command</kbd> e pressionar a tecla <kbd>B</kbd>.
    

  •       <kbd>G</kbd><kbd>I</kbd> indica que o usuário deve pressionar a tecla <kbd>G</kbd> e, depois, pressionar a tecla <kbd>I</kbd>.
    

• Ao descrever um atalho de teclado para vários sistemas operacionais, acrescente o sistema operacional entre colchetes após o atalho. Descreva primeiro o atalho do Mac e, em seguida, o do Windows/do Linux.

  •       **Use:**`<kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux)`, apresentado como:
    
    
          <kbd>Command</kbd>+<kbd>B</kbd> (Mac) ou <kbd>CTRL</kbd>+<kbd>B</kbd> (Windows/Linux)
    

  •       **Evite:**`<kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd>`, apresentado como:
    
    
          <kbd>CTRL</kbd>+<kbd>B</kbd> ou <kbd>Command</kbd>+<kbd>B</kbd>
    

Conteúdo licenciado

O GitHub Docs é licenciado sob uma licença CC-BY. Se você reutilizar ou modificar o conteúdo licenciado em um artigo, precisará garantir que a licença seja compatível e atribuída corretamente.

Não crie reutilizáveis para atribuições de licença. Precisamos usar a licença exata na qual um projeto está licenciado, ou seja, todas as atribuições precisam ser escritas com precisão para os artigos em que elas aparecem.

Se você não tiver certeza da legalidade de reutilização de qualquer conteúdo, entre em contato com o departamento jurídico. Se você estiver adicionando um conteúdo com uma licença que não está listada aqui, precisará receber uma revisão legal antes de publicar o conteúdo.

Como atribuir um conteúdo licenciado pelo MIT

Se reutilizarmos ou modificarmos o conteúdo sob uma licença MIT, precisamos atribuir a licença MIT na qual o conteúdo aparece.

No final do artigo que traz um conteúdo licenciado pelo MIT

• Crie um cabeçalho intitulado Legal notice
• Atribua a origem do conteúdo e indique que ele é licenciado sob a licença MIT. Inclua um link para o projeto
• Cole o texto completo da licença MIT do projeto que você está atribuindo em um bloco de código

Exemplo de atribuição de licença MIT

Este texto é apenas um exemplo. Sempre use o texto de licença do projeto que você está atribuindo.

## Legal notice

Portions have been adapted from [PROJECT](/LINK/TO/PROJECT) under the MIT license:

```
MIT License

Copyright YEAR COPYRIGHT-HOLDER

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```

Quebras de linha

Para um texto sem formatação, use quebras de linha para separar parágrafos na origem (duas quebras de linha consecutivas), em vez de criar um espaço visual na origem. Evite quebras de linha desnecessárias, especialmente em listas.

Links

Os links são usados para conectar as pessoas a informações adicionais e para progredir em tarefas que exigem a leitura de vários artigos.

          **Seja frugal com links.** Incluir muitos links pode distrair do conteúdo principal ou desviar o foco das pessoas. Todos os links devem ser considerados no contexto da jornada do usuário: por que devemos enviar alguém para este link e como podemos trazer de volta ao caminho certo para concluir sua tarefa?

Antes de adicionar um link, decida se alguém precisa visitar o link para entender o conteúdo ou ser bem-sucedido no uso do GitHub.

• Se o link não for necessário, remova-o.
• Se o link estiver relacionado ao tópico principal de um artigo e permitir que alguém continue aprendendo, mas não for necessário para concluir a tarefa, considere mover o link para o final do artigo como leitura adicional.
• Se o link levar alguém para a próxima etapa de um processo, inclua o link em uma seção de próximas etapas no final do artigo.
• Se o link fornecer informações que podem ser críticas para concluir uma tarefa ou solucionar problemas de uma etapa, inclua o link no corpo principal do artigo.

Os links devem ser consistentes, acessíveis ao maior número possível de pessoas, traduzíveis e claros. As pessoas precisam saber para onde um link leva e como ele se relaciona com o que elas querem realizar.

Algumas melhores práticas para o uso de links:

• Os links devem ser significativos e fornecer um valor alto para o percurso do usuário. Insira links com cuidado.
• Não repita o mesmo link mais de uma vez no mesmo artigo.
• Recomenda-se adicionar "anteriormente/posteriormente neste artigo" após um link para uma seção no mesmo artigo.
• Não inclua o parâmetro de consulta apiVersion em links REST, a menos que precise criar um link para uma versão específica do calendário da documentação da REST (essa deve ser uma ocorrência rara).

Formatação de links

É possível introduzir links apenas com o verbo "veja" se o contexto deixar claro para que serve o link. Se o contexto não estiver claro, use uma frase ou sentença para introduzir o link, como "Para obter mais informações, consulte" ou "Para saber mais sobre X, consulte Y".

Use o título do artigo de documentação, ou página da Web externa, como o texto do link. Para qualquer link que aponte para outra página do site GitHub Docs, use a palavra-chave especial AUTOTITLE para o texto do link. Confira detalhes na referência de marcação de conteúdo.

Não aplique nenhum estilo aos links nem coloque-os entre aspas.

• Em caso de links para outras páginas: See [AUTOTITLE](/PATH/TO/PAGE).
• Em caso de links para seções em outras páginas: For more information, see [AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK).

Não use links embutidos, onde as palavras dentro da frase são hiperlinks sem palavras adicionais para indicar que a frase contém um link. Isso pode ser difícil de traduzir e de ler.

Não inclua marcas de pontuação em um hiperlink.

•         **Usar:**`OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) and [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps).`
  

•         **Evite:**`Read [more about OAuth2](/apps/building-integrations/setting-up-and-registering-oauth-apps/). Note that OAuth2 tokens can be [acquired programmatically](/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.`
  

Ligações entre versões

Às vezes, você precisa vincular de uma versão de GitHub Docs para outra. Quando desejar criar um link para outra versão da mesma página, use a propriedade currentArticle.

Por exemplo, a versão Gratuita, Pro & Team de Gerenciando a publicação de sites do GitHub Pages para sua organização pode ser vinculada à versão do GitHub Enterprise Cloud do mesmo artigo desta forma:

You can choose to allow or disallow the publication of GitHub Pages sites.

Organizations that use {% data variables.product.prodname_ghe_cloud %} can choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).

Para vinculá-la a outro artigo em uma versão diferente, use este formato:

For more information, see [ARTICLE TITLE](/) in the VERSION documentation.

Para vinculá-la ao mesmo artigo em uma versão diferente, use este formato:

For more information, see [the VERSION documentation](/VERSION/{{ currentArticle }}).

Para vinculá-la a uma versão específica, inclua a versão no caminho (por exemplo, /enterprise-cloud@latest/{{ currentArticle }}).

Links para seções específicas de artigos

Links para seções específicas de artigos devem ser descritivos o suficiente para que alguém entenda que eles estão no local correto depois de seguir um link.

Para criar um link para um cabeçalho específico no mesmo artigo, use este formato:

For more information, see [HEADER TITLE](#HEADER-TITLE), later in this article.

Os links da seção na mesma página não funcionam com AUTOTITLE. Em vez disso, digite o texto completo do cabeçalho.

Para criar um link para um cabeçalho específico em um artigo diferente, use este formato:

For more information, see [AUTOTITLE](PATH-TO-ARTICLE#HEADER-TITLE).

Para criar um link para dois ou mais cabeçalhos específicos em um artigo diferente, use este formato:

For more information, see [HEADER-TITLE-1](PATH-TO-ARTICLE#SECTION-LINK-1) and [HEADER-TITLE-2](PATH-TO-ARTICLE#SECTION-LINK-2) in "ARTICLE-TITLE."

Links para uma ferramenta específica

Se você fizer um link para o conteúdo com uma ferramenta específica selecionada, certifique-se de que esteja claro que o link será para uma ferramenta específica, mesmo que alguém não interaja com a guia do seletor de ferramentas no artigo.

For more information, see the TOOLNAME documentation in [ARTICLE TITLE](/PATH/TO/ARTICLE?tool=TOOLNAME).

Links para caminhos de aprendizagem

Use este formato para criar um link para um roteiro de aprendizagem.

For more information, follow the [LEARNING PATH TITLE](/) learning path.

Links para recursos externos

Ao fazer um link para um site externo, escolha o recurso mais útil para o contexto do link. Você pode fazer o link para um site inteiro se for uma referência geral ou a uma página específica, se isso for mais útil.

Não é necessário criar um link para o site de um produto externo quando mencionamos um produto externo.

Para links que direcionam para uma página externa (qualquer site que não seja gerenciado por GitHub), digite o título de página completo e o site de destino. Não coloque o link entre aspas.

•         **Usar:**`See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.`
  

•         **Evite:**`See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE).`
  

•         **Evite:**`See [the OTHER WEBSITE](https://some-docs.com/PATH/TO/PAGE).`
  

Como adicionar âncoras para preservar links

Se você sabe que existem links para uma seção específica de um artigo, poderá adicionar uma âncora à seção para preservar o link. Por exemplo, se um recurso externo estiver vinculado a uma seção específica de um artigo, você poderá adicionar uma âncora para que o link direcione para a seção adequada, mesmo que o título da seção sofra alterações.

Use este formato para âncoras de link. O nome da âncora deve coincidir com o nome da seção que está sendo preservada. Use um comentário do HTML para explicar a razão pela qual você está adicionando a âncora.

<!-- Anchor to maintain the current example link. -->
<a name="SECTION-TITLE-THAT-MIGHT-CHANGE"></a>

Listas

Coloque em maiúsculas a primeira letra de cada linha de uma lista. Use ponto final no final das linhas de uma lista somente se a linha contiver uma frase completa.

Ao escrever uma lista de itens que consistem em um texto primário e secundário, como um term e a respectiva definição, use um delimitador de dois-pontos. É preciso usar maiúsculas no texto secundário como se ele fosse o início da linha. Por exemplo:

•         `foo`: algo que fornece bar.
  

•         `bar`: algo fornecido por foo.
  

Formatação de listas não ordenadas:

• Se a ordem dos itens na lista não for importante, coloque os itens da lista em ordem alfabética.
• Se a ordem for importante, ordene a lista pela importância para o leitor (por exemplo, migrando do público-alvo e da aplicabilidade mais amplos para um público-alvo mais especializado).
• Use asteriscos (*) para itens de lista.

Ao introduzir uma lista, evite usar frases curtas e não específicas com termos como “o seguinte” ou “estes”, os quais são difíceis de localizar sem contexto. Em vez disso, crie uma frase descritiva que transmita claramente o assunto da lista, mas que permita que a lista escale ou seja alterada sem ter que atualizar a descrição.

          **Use:**

• Para ter uma introdução ao GitHub, confira os seguintes artigos:

• Países que oferecem suporte à autenticação SMS:

          **Evitar**:
  

• Há vários artigos que fornecem uma introdução ao GitHub. Veja o seguinte:

• Há suporte para a autenticação SMS em 50 países. Estão incluídos:

Instruções de permissões e textos explicativos de produtos

Use instruções de permissões e textos explicativos de produtos para comunicar tarefas que exijam funções ou produtos específicos para serem concluídos.

•         [
          **Declarações de permissões**](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#permissions-statements): a função necessária para realizar uma ação ou tarefa descrita no artigo. Exemplo: "Proprietários de empresas".
  

•         [
          **Texto explicativo do produto**](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#product-callout): o produto ou produtos necessários para executar uma ação ou executar uma tarefa descrita no artigo. Exemplo: "Contas de organizações e empresas com uma assinatura de Copilot Business."
  

Juntas, as declarações de permissão e as chamadas de produtos informam aos leitores quem pode usar o recurso que está sendo descrito em um artigo.

Diretrizes para a criação de textos explicativos de produtos digitalizáveis

Definir permissões versus requisitos do produto

Considere quais informações pertencem a uma declaração de permissão ou a um texto explicativo do produto.

Por exemplo, ao criar permissões e chamadas de produtos para o artigo Gerenciando políticas e recursos para GitHub Copilot em sua organização, a instrução de permissão responderia "Qual função pode gerenciar políticas e recursos para o GitHub Copilot em uma organização?" E o texto explicativo do produto responderia "De quais assinaturas do Copilot os usuários precisam para gerenciar as políticas e os recursos do Copilot de uma organização?"

Concentre-se em informações-chave, e não em explicações

Instruções de permissões e os textos explicativos do produto precisam comunicar quem pode executar uma tarefa e qual produto é necessário. Eles não precisam explicar por que uma função ou produto é necessário.

Se várias funções ou produtos se aplicarem a uma instrução de permissões ou texto explicativo de produto, formate-os usando uma lista não ordenada. Você pode introduzir instruções de permissões complexas e textos explicativos de produtos com uma frase, mas sempre tente usar o mínimo de palavras necessário para comunicar quem pode fazer o que está sendo abordado no artigo.

Usar links embutidos

Você pode usar links embutidos para fornecer mais informações sobre uma função ou produto. O texto vinculado deve corresponder ao destino do link para que fique claro para onde o link levará.

Espaços reservados

Defina o estilo de qualquer texto de espaço reservado em letras maiúsculas. Se um espaço reservado for de várias palavras, conecte-as com traços (kebab-case). Se você usar um espaço reservado, explique pelo que alguém poderá substituí-lo. Isso ajuda as pessoas a modificar exemplos para atender às suas necessidades e ajuda a identificar espaços reservados para pessoas que usam tecnologia adaptativa.

          **Use:**

• Substitua YOUR-REPOSITORY pelo nome do seu repositório no exemplo a seguir. git init YOUR-REPOSITORY

• Clique em Adicionar USERNAME. Em que USERNAME é o nome de usuário da pessoa que você deseja adicionar.

          **Evitar**:
  

• git init your repository

• git init <your-repository>

• Clique em Adicionar username.

Etapas de procedimentos

Os procedimentos dão aos leitores um conjunto de etapas sequenciais a serem seguidas para realizar uma tarefa. Sempre use listas numeradas para procedimentos. Forneça aos leitores todos os pré-requisitos ou informações conceituais de que precisarão para concluir a tarefa antes do procedimento, em vez de incluí-los em uma etapa específica.

Cada etapa precisa incluir uma ação. Você também pode optar por incluir se uma etapa é opcional, explicar o motivo ou o resultado da etapa e orientar o leitor descrevendo o local da ação, antes de orientá-lo a concluir a ação.

Use uma ordem consistente para apresentar as informações em cada etapa.

1. Se a etapa for opcional, indique isso primeiro.

2. Quando necessário para fins de clareza ou para reforçar a gravidade de uma ação destrutiva ou confusa, explique o motivo ou o resultado da etapa.

3. Descreva o local em que o usuário encontrará a ação.

4. Ação.

          **Use:** opcionalmente, para `REASON`, em `LOCATION`, use `ACTION`.
   

Exemplos:

• Clique em Informações de pagamento.
• Sob o nome da organização, clique em Configurações.
• Para confirmar a alteração, clique em Remover cartão de crédito.
• Opcionalmente, para ver os detalhes do seu plano, clique em Mostrar detalhes.
• Em "GitHub Sponsors", à direita do contribuidor de código aberto patrocinado, clique em ao lado do seu valor de patrocínio, e depois clique em Alterar tier.

Nomes de produtos

Use os nomes completos dos produtos. Não abrevie nem encurte os nomes de produtos, a menos que esteja reproduzindo diretamente o conteúdo do produto (por exemplo, cópia da interface do usuário ou respostas à API). Os nomes dos produtos nunca são possessivos.

Use variáveis de nome de produto para renderizar nomes de produtos: não escreva nomes de produtos em texto sem formatação. Isso facilita a implementação de alterações de nomes de produtos em todo o site e evita erros de digitação nos nomes de produtos. Para obter mais informações sobre as variáveis de nomes de produtos, confira “Reutilizáveis e variáveis” neste documento e o diretório de dados do repositório github/docs.

Os nomes de produtos são sempre escritos no singular. * Use: o GitHub Actions ajuda você a automatizar seus fluxos de trabalho de desenvolvimento de software. * Evite: os GitHub Actions ajudam você a automatizar seus fluxos de trabalho de desenvolvimento de software.

Fique atento para distinguir os nomes de produtos dos recursos dos produtos. As características dos produtos são sempre em letras minúsculas.

Não coloque em maiúsculas os recursos comumente usados, como solicitações pull, tópicos ou problemas.

Convenções específicas do produto

Esta seção descreve convenções adicionais específicas dos produtos do GitHub.

GitHub Actions

Reutilizáveis para ações internas

Os exemplos de código que usam ações internas precisam usar o respectivo reutilizável para essa ação. Isso facilita o gerenciamento de atualizações de versão de ação (por exemplo, de v1 para v2) para produtos como o GitHub Enterprise Server, que talvez não tenham a mesma versão de ação disponível até uma versão futura do GitHub Enterprise Server.

As ações reutilizáveis estão localizadas em /data/reusables/actions/ e têm um nome de arquivo como action-<action_name>.md

Por exemplo, para usar a ação actions/checkout em um exemplo, use o respectivo reutilizável:

steps:
  - name: Checkout
    uses: actions/checkout@v5

Para fins do GitHub Docs, uma ação interna é qualquer ação que tenha o prefixo actions/, github/ ou octo-org/. Por exemplo, esta é uma ação interna:

steps:
  - uses: actions/checkout@v5

Aviso de isenção de responsabilidade para ações de terceiros

Os exemplos de código que usam ações de terceiros precisam incluir o seguinte aviso de isenção de responsabilidade como parte do bloco de código:

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

Para inserir esse aviso de isenção de responsabilidade, use o reutilizável {% data reusables.actions.actions-not-certified-by-github-comment %}.

Para fins do GitHub Docs, uma ação de terceiros é qualquer ação que não tenha o prefixo actions/, github/ ou octo-org/. Por exemplo, esta é uma ação interna:

steps:
  - uses: actions/checkout@main

Este é um exemplo de uma ação de terceiros:

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

Exemplos:

• Confira o bloco de código em Publicação em registros de pacote

Como fixar números de versão no SHA

Os exemplos de código que usam ações de terceiros precisam sempre ser fixados em um SHA de commit de comprimento completo, em vez do número de versão ou do branch:

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

Para fins do GitHub Docs, uma ação de terceiros é qualquer ação que não tenha um dos seguintes prefixos: actions/, github/ e octo-org/. Por exemplo, esta é uma ação interna:

steps:
  - uses: actions/javascript-action@main

Para saber mais, confira Como usar SHAs

Codespaces

Ao referenciar o produto Codespaces, sempre inclua "GitHub", exceto nestas circunstâncias:

• Na matéria de capa shortTitle.
• Em subtítulos em um artigo, se o "Codespaces" já tiver sido usado em qualquer lugar no artigo antes do subtítulo.

Variáveis: {% data variables.product.prodname_github_codespaces %} ("GitHub Codespaces") e {% data variables.product.prodname_codespaces %} ("Codespaces").

Ao se referir às instâncias de ambientes de trabalho remoto criadas com essa tecnologia, refira-se a eles como "codespaces" (com c minúsculo). Por exemplo, "para excluir seu codespace" ou "para listar seus codespaces".

Sempre use "contêiner de desenvolvimento" (ou, quando for necessário um esclarecimento, a forma mais longa "contêiner de desenvolvimento") e não "devcontainer" (uma palavra), exceto em nomes de arquivo/caminho. A palavra única poderia ser considerada uma marca, o que desejamos evitar. Além disso, queremos ser consistentes com o formato de duas palavras usado na documentação do Visual Studio Code.

Use "arquivos de configuração do contêiner de desenvolvimento" para se referir a todos os arquivos do diretório .devcontainer (mais o .devcontainer.json se ele estiver sendo usado em vez de devcontainer.json no diretório .devcontainer). Não se refira a eles como "arquivos de contêiner de desenvolvimento" ou "arquivos de devcontainer" para evitar que isso seja entendido como arquivos devcontainer.json. "Arquivos de configuração do contêiner de desenvolvimento" referem-se a todos os arquivos que podem ser usados para configurar um contêiner de desenvolvimento, incluindo arquivos Dockerfile e compose.yaml. Não use "o arquivo de configuração do contêiner de desenvolvimento" (singular) ao se referir especificamente a um arquivo devcontainer.json. Em vez disso, refira-se a esse arquivo pelo nome.

Produtos GitHub Advanced Security (GHAS)

Use os termos licenses e active committers quando você se referir à cobrança de GitHub Advanced Security, GitHub Code Security ou GitHub Secret Protection.

Usávamos a expressão seats para descrever o número de contas que podem usar GitHub Advanced Security, GitHub Code Security, ou GitHub Secret Protection em uma empresa. O termo seats pode confundir as pessoas, então foi removido do GitHub.com em 2022. As versões do GHES 3.7 em diante não o usam.

Personal access tokens

O GitHub tem dois tipos de personal access tokens:

• Fine-grained personal access tokens: oferecem controle granular sobre o acesso e as permissões do repositório
• Personal access token (classic): utiliza escopos e permite acesso a todos os repositórios que o proprietário do token pode acessar

Você deve usar variáveis para referenciar esses tipos de tokens, assim como personal access tokens em geral.

• Use {% data variables.product.pat_generic %} ou {% data variables.product.pat_generic_caps %} para se referir a personal access token em geral. Use {% data variables.product.pat_generic_title_case %} se a frase deve usar maiúsculas em todas as palavras ("Personal Access Token") para corresponder ao texto da interface do usuário.
• Use {% data variables.product.pat_v2 %} ou {% data variables.product.pat_v2_caps %} para se referir a fine-grained personal access tokens.
• Use {% data variables.product.pat_v1 %}, {% data variables.product.pat_v1_plural %}, {% data variables.product.pat_v1_caps %} ou {% data variables.product.pat_v1_caps_plural %} para se referir a personal access token (classic).

Para saber mais sobre os personal access tokens do GitHub, confira Gerenciar seus tokens de acesso pessoal.

Pontuação

Siga as regras de pontuação padrão do inglês dos EUA. Para obter mais diretrizes, confira “Pontuação” no Guia de Estilo da Microsoft.

Notas de versão

Um conjunto de notas sobre a versão do GitHub Docs informa aos leitores sobre as alterações voltadas para o administrador ou para o usuário em uma versão de um produto como o GHES (GitHub Enterprise Server). As notas de lançamento aparecem em Notas de versão.

Uma boa nota de versão consiste em algumas frases que, de forma sequencial, respondem às perguntas do leitor sobre a alteração. Para saber mais, confira Tipo de conteúdo das notas de versão.

Cada nota sobre a versão em um conjunto descreve uma das alterações a seguir.

•         [Recursos](#features): novo comportamento ou funcionalidade
  

•         [Correções de segurança](#security-fixes): correções de falhas ou de comportamento inesperado que têm implicações de segurança
  

•         [Correções de bug](#bug-fixes): correções de falhas ou de comportamento inesperado
  

•         [Alterações](#changes): alterações importantes no comportamento anterior
  

•         [Problemas conhecidos](#known-issues): problemas que a GitHub identificou, mas ainda não conseguiu ou ainda não priorizou
  

•         [Desativação](#closing-down): o processo de preterição; não deve mais ser usado para trabalhos futuros
  

•         [Desativado](#retired): fim do ciclo de vida de um produto ou recurso
  

•         [Errata](#errata): correção de uma nota sobre a versão ou de uma documentação incorreta
  

Você também pode revisar as diretrizes para atualizar as notas de versão em Adicionar ou atualizar uma nota de versão e Remover uma nota de versão.

Recursos

Uma nota de versão de um recurso resume um comportamento totalmente novo. Em geral, as notas sobre os recursos fazem parte apenas dos lançamentos de recursos.

Como escrever notas de lançamento de funcionalidades

A nota de lançamento de um recurso responde às perguntas a seguir.

1. Essa nova funcionalidade se aplica a mim, considerando minha função ou meu nível de acesso?
2. Qual é a necessidade que a funcionalidade satisfaz?
3. Qual é a funcionalidade?
4. Se aplicável, onde posso ler mais sobre a funcionalidade?

          _PÚBLICO-ALVO_ (**1**) pode _DESCRIÇÃO DA NECESSIDADE_ (**2**) por _DESCRIÇÃO DO USO DO RECURSO_ (**3**). Para saber mais, confira [_TÍTULO DO ARTIGO_](/) (**4**)

• Categorize cada recurso em uma seção, sob o título de um recurso.
• Escreva no presente.
• Para reduzir a repetição e palavras desnecessárias, a palavra "agora" em geral está implícita.
• A fim de esclarecer os atores e o impacto, evite usar a linguagem passiva quando possível.

Exemplos de notas sobre a versão de recursos

• Os administradores do site podem aumentar a segurança do Console de Gerenciamento configurando o limite de taxa para tentativas de entrada, bem como a duração do bloqueio depois que o limite de taxa é excedido. Para saber mais, confira Configuração de limites de taxas.

• Os proprietários da empresa podem controlar onde os usuários podem criar forks nos repositórios. A criação de fork pode ser limitada a combinações predefinidas das organizações, à mesma organização que o repositório pai, às contas de usuários ou a todos os lugares. Para saber mais, confira Como impor políticas de gerenciamento de repositório na sua empresa.

• Os usuários podem criar arquivos com diagramas geoJSON, topoJSON e STL e renderizar os diagramas na interface da Web. Para saber mais, confira Trabalhar com arquivos sem código.

Correções de segurança

Nota de lançamento para uma correção de segurança resume uma alteração que atenua ou impede a exploração de um problema relacionado à segurança no produto. Em geral, as notas sobre correções de segurança são apenas parte das versões de patch.

Como escrever notas sobre a versão para correções de segurança

Nota de versão para correção de segurança responde às perguntas a seguir.

1. Se disponível, qual é a classificação de gravidade da vulnerabilidade no NVD para a vulnerabilidade corrigida?
2. Qual é o ataque que um invasor pode realizar explorando a vulnerabilidade?
3. Que tipo de vulnerabilidade é explorável?
4. Se disponível, qual é o identificador de CVE da vulnerabilidade, pendente ou ativo?
5. Alguém relatou a vulnerabilidade por meio do Programa de Recompensas por Bugs do GitHub?

          _GRAVIDADE_ (**1**): um invasor pode _DESCRIÇÃO DO IMPACTO_ (**2**) por _DESCRIÇÃO DA EXPLORAÇÃO_ (**3**). O GitHub solicitou a ID de CVE [_CVE-####-#####_](/) (**4**) para essa vulnerabilidade, que foi relatada por meio do [Programa de Recompensas por Bugs do GitHub](https://bounty.github.com) (**5**).

Exemplos de notas de lançamento para correções de segurança

•         **MÉDIA**: um invasor pode causar esgotamento ilimitado de recursos na instância fazendo solicitações paralelas à API REST do Markdown. Para atenuar esse problema, o GitHub atualizou o [CommonMarker](https://github.com/gjtorikian/commonmarker). O GitHub solicitou a ID de CVE [CVE-2022-39209](https://nvd.nist.gov/vuln/detail/CVE-2022-39209) para essa vulnerabilidade.
  

•         **MÉDIA:** um invasor pode inserir links perigosos na interface do usuário da Web da instância, porque os links de visualização da pull request não limparam corretamente as URLs. Essa vulnerabilidade foi relatada pelo [Programa de Recompensas por Bugs do GitHub](https://bounty.github.com).
  

Atualizações de pacote e imagem de base

Também incluímos atualizações de pacote dependente e imagem base na seção "Correções de segurança", já que essas atualizações geralmente abordam problemas de segurança. Consolidamos todas essas atualizações na nota a seguir.

Os pacotes foram atualizados para as versões de segurança mais recentes.

Correções de bug

Uma nota sobre a versão para uma correção de bug descreve uma correção para um comportamento indesejado ou inesperado. Em geral, as notas sobre correções de bugs são apenas parte das versões de patch.

Como escrever notas de lançamento sobre correções de bugs

Uma nota de lançamento para uma correção de bug responde as seguintes perguntas.

1. Esse comportamento me afetou na minha função ou no meu acesso?
2. Qual comportamento o leitor experimentará antes da correção?

          _PÚBLICO-ALVO_ (**1**) _DESCRIÇÃO DO COMPORTAMENTO_ (**2**).

• Como o bug já foi corrigido, escreva-o no tempo passado.
• A frase "Correção de um bug…" ou "Correção de um problema…" é implícita e desnecessária.
• Para reduzir a repetição e palavras desnecessárias, a palavra "agora" em geral está implícita.
• A fim de esclarecer os atores e o impacto, evite usar a linguagem passiva quando possível.
• Se a nota de versão incluir uma mensagem de erro, faça a formatação seguindo as diretrizes em Mensagens de erro.

Exemplos de notas de lançamento para correções de bugs

• Depois que um usuário importava um repositório com a proteção por push habilitada, o repositório não ficava imediatamente visível na exibição "Cobertura de Segurança" da visão geral de segurança.

• Em uma instância com o GitHub Actions habilitado, um trabalho de fluxo de trabalho do GitHub Actions não era iniciado se um grupo de executores correspondente não estivesse disponível quando o trabalho era inicialmente colocado na fila, mesmo que um grupo de executores correspondente ficasse disponível depois que o trabalho entrasse na fila.

• Os comandos que os administradores do site executaram por meio do SSH em um dos nós de instâncias não eram registrados em /var/log/ssh-console-audit.log.

Alterações

Uma nota sobre a versão para uma alteração descreve uma alteração importante, mas secundária no comportamento existente. As observações de alterações respondem às perguntas a seguir.

Como escrever notas sobre a versão para alterações

Uma nota sobre a versão para uma alteração responde às perguntas a seguir.

1. Esse comportamento me afetou na minha função ou no meu acesso?
2. Se a alteração resolve ou evita um problema, qual é o problema?
3. Qual é o novo comportamento?
4. Se relevante, qual era o comportamento antes da alteração?

          _PÚBLICO-ALVO_ (**1**) / _DESCRIÇÃO DO PROBLEMA QUE A ALTERAÇÃO RESOLVE_ (**2**) _DESCRIÇÃO DO NOVO COMPORTAMENTO_ (**3**) _DESCRIÇÃO DO COMPORTAMENTO ANTIGO_ (**4**).

• Como a alteração se aplica à versão em questão, escreva as notas de alterações no presente simples.
• Para reduzir a repetição e palavras desnecessárias, a palavra "agora" em geral está implícita.
• A fim de esclarecer os atores e o impacto, evite usar a linguagem passiva quando possível.
• Muitas vezes, o público-alvo está implícito.
• Se isso for útil, inclua links relevantes para o GitHub Docs.

Exemplos de notas de lançamento para alterações

• Em uma instância com uma licença para GitHub Advanced Security ou GitHub Secret Protection, os usuários que criarem padrões personalizados para verificação de segredo podem fornecer expressões que devem ou não corresponder a até 2.000 caracteres. Esse limite é um aumento em relação ao limite anterior de mil caracteres.

• Para os administradores que precisam analisar ou modificar os mapeamentos de SAML, o caminho padrão para a saída de ghe-saml-mapping-csv -d é /data/user/tmp em vez de /tmp. Para saber mais, confira Utilitários de linha de comando.

• Para evitar problemas intermitentes com o sucesso das operações do Git em uma instância com vários nós, o GitHub Enterprise Server verifica o status do contêiner do MySQL antes de tentar executar uma consulta SQL. A duração do tempo limite também foi reduzida.

Problemas conhecidos

Uma nota de lançamento para um problema conhecido relata um problema que o GitHub identificou, mas não pode ou ainda não priorizou.

Como escrever notas sobre a versão para problemas conhecidos

Uma nota sobre a versão para um problema conhecido responde às perguntas a seguir.

1. Esse comportamento afeta meu acesso ou minha função?
2. Quais são as mensagens de erro ou outros elementos de interface do usuário reconhecíveis exibidos?
3. Preciso executar alguma ação? Nesse caso, o que devo fazer?

          _PÚBLICO-ALVO_ (**1**) _DESCRIÇÃO DO PROBLEMA_ (**2**) _DETALHES DO COMPORTAMENTO_ (**3**) _PRÓXIMAS ETAPAS_ (**4**).

• A fim de esclarecer os atores e o impacto, evite usar a linguagem passiva quando possível.
• Para reduzir a repetição e palavras desnecessárias, a palavra "agora" em geral está implícita.
• Se a nota de versão incluir uma mensagem de erro, faça a formatação seguindo as diretrizes em Mensagens de erro.
• Se isso for útil, inclua links relevantes para o GitHub Docs.
• Problemas conhecidos também são um tipo de conteúdo no GitHub Docs. Para saber mais, confira Tipo de conteúdo de solução de problemas. Se for útil, escreva ou vincule a conteúdo mais aprofundado e contextualmente relevante nos documentos.

Exemplos de notas sobre a versão para problemas conhecidos

• Depois que um usuário habilita a opção de um repositório para permitir que os usuários com acesso de leitura criem discussões, o recurso não é habilitado.

• Depois que um administrador inicia uma execução de configuração, um No such object error pode ocorrer durante a fase de validação nos serviços Notebook e Viewscreen. Esse erro pode ser ignorado, pois os serviços ainda devem ser iniciados corretamente.

Desativação

Uma nota de lançamento sobre um recurso que está sendo desativado resume um comportamento ou recurso que o GitHub planeja remover. Esses recursos ainda estão disponíveis para uso em produção e vêm com os SLAs de suporte associados e as obrigações de suporte técnico. No entanto, eles estão em processo de aposentadoria e não se deve mais confiar neles para trabalhos futuros. A desativação é um estágio de transição no qual os usuários são aconselhados a parar de usar o recurso e se preparar para sua preterição.

Escrever notas de lançamento sobre recursos que estão sendo descontinuados

Uma nota de versão para um recurso que está sendo encerrado responde às perguntas a seguir.

1. Esta funcionalidade existente é aplicável ao meu caso, levando em consideração minha função ou meu acesso?
2. Qual é a funcionalidade que está sendo desativada?
3. Se aplicável, o que substitui a funcionalidade que está sendo desativada?
4. Se aplicável, onde posso ler mais sobre ela?

          _PÚBLICO-ALVO_ (**1**) _DESCRIÇÃO DA FUNCIONALIDADE QUE ESTÁ SENDO DESATIVADA_ (**2**) _FUNCIONALIDADE SUBSTITUTA_ (**3**) Para saber mais, confira [_TÍTULO DO ARTIGO_](/) (**4**).

• As notas são escritas no presente simples ou no futuro simples para as próximas alterações. Se aplicável, especifique o próximo lançamento em que a aposentadoria ocorrerá.
• Para reduzir a repetição e palavras desnecessárias, a palavra "agora" em geral está implícita.
• A fim de esclarecer os atores e o impacto, evite usar a linguagem passiva quando possível.
• Categorize cada recurso em uma seção, sob o título de um recurso.

Exemplos de notas de lançamento para recursos que estão sendo desativados

•         **Desativação:**: no GitHub Enterprise Server 3.8 e posterior, para garantir a segurança da instância, os algoritmos não seguros serão desabilitados para conexões SSH com o shell administrativo.
  

• Os comentários de commit, que são comentários adicionados diretamente por usuários a um commit fora de um pull request, não aparecem mais na cronologia do pull request. Os usuários não puderam responder ou resolver esses comentários. A API REST de eventos da Linha do Tempo e o objeto PullRequest da API do GraphQL também não retornam mais comentários de commit.

Retirado

Produtos ou recursos descontinuados não estão mais disponíveis para novos clientes, não são mais comercializados, suportados ou documentados. Nesta fase, o produto é efetivamente descontinuado e nenhum novo desenvolvimento ou correção será fornecido. O único suporte para produtos preteridos pode vir de compromissos existentes, como os necessários para as versões lançadas anteriormente de GitHub Enterprise Server. A desativação marca o fim oficial do ciclo de vida de um produto ou recurso, sem mais atualizações, correções de bugs ou suporte ao usuário, sinalizando uma transição completa para ferramentas ou serviços mais recentes.

Como escrever notas de lançamento para recursos descontinuados

Uma nota de versão de um recurso descontinuado responde às perguntas a seguir.

1. Esta funcionalidade se aplica a mim, considerando minha função ou acesso?
2. Qual é a funcionalidade que está sendo preterida?
3. Se aplicável, o que substitui a funcionalidade preterida?
4. Se aplicável, onde posso ler mais sobre ela?

          _PÚBLICO-ALVO_ (**1**) _DESCRIÇÃO DA FUNCIONALIDADE PRETERIDA_ (**2**) _FUNCIONALIDADE SUBSTITUTA_ (**3**) Para saber mais, confira [_TÍTULO DO ARTIGO_](/) (**4**)

• As notas estão no tempo presente.
• Para reduzir a repetição e palavras desnecessárias, a palavra "agora" em geral está implícita.
• A fim de esclarecer os atores e o impacto, evite usar a linguagem passiva quando possível.
• Categorize cada recurso em uma seção, sob o título de um recurso.

Exemplos de notas de release para funcionalidades descontinuadas

•         **Preterido**: GitHub não dá mais suporte a fluxos de trabalho necessários para GitHub Actions em GitHub Enterprise Server 3.11 e posterior. Em vez disso, use conjuntos de regras do repositório. Para saber mais, confira [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging).
  

Errata

A errata corrige informações incorretas publicadas anteriormente nas notas sobre a versão ou na documentação de uma versão.

Come escrever uma errata

A errata responde às perguntas a seguir.

1. Se aplicável, qual seção das notas sobre a versão ou do conteúdo do GitHub Docs foi afetada?
2. As informações incorretas se aplicavam a mim, considerando minha função ou meu acesso?
3. O que a nota sobre a versão ou a documentação descrevia que estava incorreto?
4. Quando a errata foi publicada?

          _CONTEÚDO_ (**1**) indicava incorretamente que o _PÚBLICO-ALVO_ (**2**) pode _RESUMO DAS INFORMAÇÕES INCORRETAS_ (**3**). [Atualizado em: _DATA DA PUBLICAÇÃO_**4**]

• Formate a data de publicação seguindo as diretrizes descritas em Como adicionar ou atualizar uma nota sobre a versão.

Exemplo de errata

•         [Recursos](/) indicava incorretamente que os usuários do GitHub Advisory Database podiam ver avisos do Elixir, do gerenciador de pacotes do Hex do Erlang, entre outros. Esse recurso não está disponível no GitHub Enterprise Server 3.7 e estará disponível em uma versão futura. [Atualizado em 01-06-2023]
  

Como adicionar ou atualizar uma nota de versão

Para sinalizar aos leitores de que você adicionou ou alterou uma nota ou para indicar a data de publicação de uma errata, acrescente um carimbo de data/hora no formato "[Atualizado em: DD-MM-YYYY]".

Remover uma nota de versão

Para sinalizar que removemos uma nota de versão, adicione uma seção "Errata" detalhando qual nota foi removida e (se relevante) a qual versão a nota removida realmente pertence. Consulte Errata de redação.

Referências de versão

Ao se referir a um intervalo de lançamentos começando por uma versão específica, use "ou posterior".

•         **Use:** "lançamento 0.41.0 ou posterior"
  

•         **Evite:** "versão 0.41.0 ou superior"
  

•         **Evite:** "versão 0.41.0 ou superior"
  

Reutilizáveis e variáveis

Use cadeias de caracteres reutilizáveis para substantivos individuais (por exemplo, nomes de produtos) ou para frases ou parágrafos completos. Fragmentos de frases e frases sem verbos não devem ser contidos em cadeias de caracteres reutilizáveis, pois poderão causar problemas quando o conteúdo for localizado. Para saber mais, confira o diretório de dados no repositório github/docs, Como criar um conteúdo reutilizável e a seção Nomes de produtos deste documento.

Sumários de seções

Se uma seção de um artigo usar cabeçalhos H3 ou H4 para dividir ainda mais o conteúdo e apenas parte do conteúdo for relevante para um leitor, use um sumário para ajudar os leitores a identificar e navegar até as informações mais relevantes para eles. Por exemplo, em Como transmitir o log de auditoria para sua empresa, provavelmente, as pessoas só vão configurar o streaming de log de auditoria para um provedor, ou seja, o sumário de seções em "Como configurar o streaming de log de auditoria" permite que as pessoas selecionem o provedor e naveguem até o conteúdo relevante sem ler a seção inteira.

Não adicione um sumário de seções se os cabeçalhos H3 ou H4 forem usados apenas para agrupar o conteúdo e todas as informações puderem ser relevantes para um leitor. Por exemplo, em Conceitos básicos de gerenciamento de identidade e acesso, as pessoas devem ler e considerar cada seção no que diz respeito às respectivas empresas. Não incluímos um sumário de seções neste artigo, porque as pessoas devem ler cada seção na íntegra, não escolhendo partes entre o conteúdo. A adição de um sumário de seções também forçará as pessoas que usam leitores de tela ou outro tipo de tecnologia adaptativa a percorrer mais cabeçalhos antes de encontrar o que precisam.

Formate os sumários de seções como uma lista. Inclua todas as subseções na ordem em que aparecem no artigo e referencie-as usando o título de cabeçalho completo.

Os sumários de seções precisam ser introduzidos com uma frase ou um parágrafo que ajude as pessoas a entender como o conteúdo é organizado e selecionar a seção mais relevante para elas. Não inclua um sumário de seções diretamente abaixo de um cabeçalho.

Exemplos de sumários de seções

## Setting up the application

Set up your application according to your operating system.

* [Setting up for macOS](#setting-up-for-macOS)
* [Setting up for Windows](#setting-up-for-windows)
* [Setting up for Linux](#setting-up-for-linux)

### Setting up for macOS

TEXT

### Setting up for Windows

The application is supported for all versions of Windows, but the set up steps differ.

* [Windows 98](#windows-98)
* [Windows Vista](#windows-vista)
* [Windows 11](#windows-11)

#### Windows 98

TEXT

#### Windows Vista

TEXT

#### Windows 11

TEXT

### Setting up for Linux

TEXT

Tabelas

As tabelas são adicionadas ao GitHub Docs usando Markdown. Como as tabelas podem ser difíceis de ler e manter, certifique-se de que os dados de uma tabela sejam representados de maneira melhor em uma tabela e não em outro formato, como uma lista, antes de criar uma tabela. Cada linha em uma tabela deve começar e terminar com um pipe, |.

Use tabelas somente para apresentar informações tabulares

As tabelas funcionam melhor para apresentar dados de tabela, como informações que precisam ser comparadas ou valores com vários atributos. Não use tabelas para listas simples. Confira a seção Listas deste documento.

Evite descrever os dados de tabela

Os dados de uma tabela e a importância deles devem estar claros a partir de qualquer conteúdo anterior, dos cabeçalhos de coluna e (se necessário) dos cabeçalhos de linha. Evite descrições desnecessárias dos dados em uma tabela. Se os dados de uma tabela não estiverem claros sem uma descrição longa, considere se a tabela precisa de cabeçalhos de linha ou se as informações serão mais bem comunicadas de outra maneira.

Por exemplo, em Referência de executores auto-hospedados, uma tabela que compara os recursos entre duas soluções de dimensionamento automático com suporte é introduzida com a frase Each solution has certain specifics that may be important to consider.. O artigo não descreve nenhum dos diferentes recursos que são comparados porque essas informações são claramente comunicadas pela tabela.

•         **Use:** "Diferentes limites de tamanho por repositório se aplicam conforme a versão do GHES".
  

•         **Evite:** "a primeira linha da tabela mostra as informações do GitHub Enterprise Cloud. A segunda linha mostra as informações do GitHub Enterprise Server".
  

•         **Evite:** “A tabela abaixo mostra os tipos de dados de migração exportados”.
  

Use a marcação adequada para cabeçalhos de linha e de coluna

As tabelas nas quais a primeira coluna descreve os valores de dados na tabela (mas que não são dados em si) precisam ser marcadas com cabeçalhos de linha. Isso é importante para que a tecnologia adaptativa entenda as relações entre as células.

Por exemplo, na tabela a seguir, para entender os valores "Sim" e "Não" da tabela, você precisa saber o cabeçalho de coluna (função) e o cabeçalho de linha (permissão).

Para adicionar cabeçalhos de linha a uma tabela Markdown, coloque a tabela entre as tags {% rowheaders %} {% endrowheaders %} do Liquid. Para obter mais informações sobre como usar cabeçalhos de linha, confira Como usar Markdown e Liquid no GitHub Docs.

Inclua um valor para cada célula

Cada célula de uma tabela precisa conter um valor.

Para células sem dados, use "Nenhum" ou "Não aplicável". Não use "NA" ou "N/A".

Para tabelas com cabeçalhos de linha, a primeira célula (célula "A1") deve descrever os cabeçalhos de linha para ajudar as pessoas a entender a tabela inteira. Porém, se isso tornar a tabela menos clara ou adicionar informações redundantes, você poderá deixar essa célula vazia. Por exemplo, no artigo Criar e testar PowerShell, a primeira célula poderia ser rotulada como "Módulos", mas, como cada cabeçalho de linha já inclui a palavra "módulo", esse cabeçalho repetiria informações que não agregam valor descritivo à compreensão da tabela no sentido mais amplo.

Use símbolos e rótulos claros e consistentes

Para as tabelas que usam símbolos:

• Preencha todas as células. Por exemplo, em uma tabela de permissões, não marque apenas as células para itens que exigem uma permissão.
• Use octicons ou SVG. Não use emojis. Para saber mais sobre octicons, confira Como usar Markdown e Liquid no GitHub Docs.
• Use uma marca de seleção para valores afirmativos ("Sim", "Obrigatório", "Com suporte") e uma cruz para valores negativos ("Não", "Opcional", "Sem suporte").
• Use aria-label para descrever o significado do símbolo, não as características visuais. Por exemplo, "Obrigatório", não "Ícone de marca de seleção".

Quando os dados da tabela não são verdadeiramente binários (cada valor é "Sim" ou "Não", por exemplo), valores de texto podem ser necessários além ou em vez de símbolos. Por exemplo, na página Sobre GitHub suporte, alguns recursos são marcados como "Disponível para compra".

Use notas de rodapé com moderação

Confira Notas de rodapé.

Alinhe o conteúdo da tabela de maneira consistente

Todas as colunas de uma tabela devem ser alinhadas à esquerda, exceto as colunas que contêm apenas octicons que devem ser alinhados no centro. Se uma coluna contiver texto e octicons, use o alinhamento central.

O conteúdo da tabela é alinhado à esquerda por padrão. Use a formatação de tabela Markdown, dois-pontos (:) à direita ou à esquerda dos traços na linha de cabeçalho, para especificar o alinhamento de cada coluna. Leia Organizar informações com tabelas para obter mais informações.

O exemplo a seguir mostra parte de uma tabela de Referência de opções do Dependabot.

A tabela é gerada com a sintaxe de alinhamento a seguir.

| Option              | Required | Security Updates | Version Updates | Description                    |
|---------------------|:--------:|:----------------:|:---------------:|--------------------------------|
| `package-ecosystem` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Package manager to use         |
| `directory`         |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Location of package manifests  |
| `schedule.interval` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| How often to check for updates |

Títulos

Use letras maiúsculas e minúsculas para títulos.

Títulos curtos

Usamos títulos curtos para preencher a navegação na barra lateral. Como os títulos curtos aparecem na navegação da barra lateral, eles podem usar o contexto para transmitir significado e serem um pouco menos exatos do que os títulos completos. A meta dos títulos curtos é ajudar as pessoas a encontrar o conteúdo que procuram sem ter itens de navegação na barra lateral longos demais. Títulos curtos dão às pessoas uma compreensão contextual de um artigo se alinham aos padrões a seguir.

• Os títulos curtos têm de duas a três palavras.
  • Para categorias, os títulos curtos devem ter menos de 27 caracteres.
  • Para tópicos de mapa, os títulos curtos devem ter menos de 30 caracteres.
  • Para artigos, os títulos curtos devem ter menos de 31 caracteres e, idealmente, entre 20 e 25 caracteres.
• Títulos curtos usam a forma base de verbos, em vez de gerúndios. * Usar: "Configurar notificações" em vez de "Configuração de notificações".
• Títulos curtos para categorias, tópicos de mapas e artigos podem omitir nomes de produtos e recursos se estiver claro a qual produto ou recurso eles se refere. * Usar: "Configurar notificações" como o título curto para Configurando notificações para alertas do Dependabot, já que o artigo está no tópico do mapa "Dependabot alerts".
• Títulos curtos não introduzem novas palavras que não estão no título completo.
• Títulos curtos devem ser consistentes com aqueles de conteúdos similares. * Usar: "Organizações e equipes" e "Contas empresariais" * Evitar: "Organizações e equipes" e "Gerenciar contas empresariais"

Escrever títulos curtos pode ser desafiador. Para ajudar a manter os títulos curtos dentro do limite de caracteres, considere o título breve no contexto. Remova todas as palavras repetidas se possível, bem como os nomes de produtos ou recursos que estejam no tópico ou na categoria do mapa ao qual o conteúdo pertence.

Conteúdo da política do site

Não use reutilizáveis ou variáveis no conteúdo da política do site. Os artigos de política do site são documentos legais e devem ter uma fonte legível por humanos.

Caso contrário, o conteúdo da política do site usa o mesmo estilo e modelos de conteúdo que o restante dos dados GitHub Docs.

Elementos da interface do usuário

Negrito

Use negrito para descrever os elementos de interface do usuário com os quais você pode interagir.

• Na barra lateral esquerda, clique em Cobrança.
• Observe a caixa de mesclagem na parte inferior da guia Conversa da pull request.
• Ao lado de Título, adicione um rótulo descritivo para a nova chave.

Nomes de branches

Use formatação de código para nomes de ramos.

• main
• USERNAME.github.io

Botões

Formate os nomes de botões em negrito e, sempre que possível, omita a palavra “botão”. Para descrever o uso de um botão, escreva “clique”, não aperte nem pressione. * Use: clique em Pull request. * Evite: pressionar o botão Pull request.

Caixas de seleção

Formate os nomes de caixas de seleção em negrito e omita a palavra “caixa de seleção”. Para descrever a escolha ou a desmarcação de uma caixa de seleção, use “selecionar” ou “desmarcar”. * Use: selecione Habilitar para todos os novos repositórios. * Evite: marcar a caixa de seleção “Habilitar para todos os novos repositórios”.

Texto dinâmico

Use letras maiúsculas para indicar um texto que muda na interface do usuário ou que o usuário precisa fornecer em um snippet de código ou em um comando. * Use: clique em Adicionar NOME DE USUÁRIO ao REPONAME.

Listas e itens de lista

Formate as listas e os itens de lista clicáveis em negrito. Para descrever a interação com uma lista, como um menu suspenso ou um elemento de interface do usuário que se expande, independentemente de o nome da lista ser uma palavra ou um octicon, escreva "selecione". Para descrever a escolha de um item de lista, escreva "clique". * Use: selecione o menu suspenso Fazer backup de endereços de email e clique em Permitir somente email primário. * Evite: clique no menu suspenso "Fazer backup de endereços de email" e clique em Permitir somente email primário.

Localidade

De acordo com as diretrizes do WCAG, devemos descrever elementos pelo nome e não apenas pela aparência ou localização. O Guia de Estilo da Microsoft oferece diretrizes específicas para frases direcionais, com ênfase em seu uso na documentação.

•         [Acima](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/above) ou [abaixo](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/b/below)
  

•         [Superior esquerdo, superior direito](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/upper-left-upper-right)
  

•         [Inferior esquerdo, inferior direito](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/l/lower-left-lower-right)
  

• Ao lado, na parte inferior ou superior da página, no lado esquerdo ou direito da página

Painéis

Quando possível, evite referenciar painéis. Em vez disso, descreva o que alguém precisa fazer. * Use: clique em Exibir gráficos e grafos no repositório e selecione o período que deseja ver no menu suspenso. * Evite: clique em Exibir tabelas e gráficos para abrir o painel do repositório selecionado e selecione o período que deseja ver no menu suspenso.

Caso você precise referenciar um painel para descrever uma alteração na interface do usuário ou para explicar como interagir com a interface do usuário, formate o nome do painel como texto da interface do usuário. Inclua apenas a palavra “painel” se ela adicionar clareza ou se o painel não tiver nenhum nome na interface do usuário.

•         **Use:** no painel "Cobertura de segurança", selecione **Habilitar** ou **Desabilitar**.
  

•         **Use:** no painel, selecione **Habilitar** ou **Desabilitar**.
  

Botões de opção

Formate os rótulos de botões de opção em negrito e omita as palavras “botão de opção” ou qualquer outro descritor. Para descrever o uso de um botão de opção, escreva "selecione".

Nomes de repositórios

Defina o estilo dos nomes de repositórios em fonte com espaçamento uniforme usando acentos graves. Forneça um link para os repositórios quando as pessoas precisarem navegar até eles. * Use: confira o repositório do github/docs para mais informações.

Elementos responsivos

Só documentamos os estados responsivos dos elementos da interface do usuário quando eles criam ambiguidade ou confusão. Se uma tarefa não estiver clara devido a um elemento de interface do usuário responsivo, descreva a interação que alguém deve fazer para atingir a meta da tarefa. Não descreva apenas o estado visual do elemento da interface do usuário.

•         **Usar:** Clique em **Segurança**. Se a opção Segurança não estiver visível, clique em **⋮** para expandir o menu do repositório.
  

Texto da interface do usuário

Ao referenciar um texto na interface do usuário, reproduza o texto com exatidão. Coloque entre aspas os textos da interface do usuário com os quais não é possível interagir. Coloque vírgulas fora das aspas.

•         **Use:** em “Lista de permissões de IP”, clique em **Editar**.
  

Mais recursos

Guia de Estilo da Microsoft: * Formatação de texto em instruções

Vídeos

Você poderá adicionar vídeos para reforçar informações baseadas em texto, mas os vídeos nunca devem substituir o conteúdo escrito. Os vídeos são inacessíveis para alguns usuários e são difíceis de encontrar por meio de pesquisa.

Os vídeos do site GitHub Docs precisam ser bem produzidos e conter menos obstáculos para pessoas com deficiências e estar em conformidade com nosso modelo de conteúdo para vídeos. Para saber mais, confira Sobre como usar vídeos no GitHub Docs.

Voz e tom

Use uma linguagem clara e simples que seja acessível para uma ampla gama de leitores. Seja autêntico, empático e confiante na sua escrita.

Escreva para seu público-alvo: alguns jargões e termos técnicos são necessários, mas não dependa da suposição de que cada leitor tem o mesmo nível de conhecimento técnico.

Use a voz ativa sempre que possível. A voz passiva é aceitável quando você precisa enfatizar o objeto de uma ação.

Somos uma comunidade de desenvolvedores globais. Evite usar expressões idiomáticas, dialetos e gírias específicas de determinada região ou país.

Para saber mais sobre como escrever um conteúdo acessível, confira “Voz da marca da Microsoft: acima de tudo, simples e humana” e “Dez principais dicas de estilo e voz da Microsoft”.

Escolha de palavras e terminologia

Para obter diretrizes gerais e termos específicos do GitHub, confira nosso Glossário. Para obter diretrizes mais detalhadas, confira a “lista de palavras de A-Z” no guia de estilo da Microsoft.

Abreviações

Escreva as palavras por extenso, exceto ao se referir a uma palavra que seja explicitamente abreviada no próprio produto. * Use: repositório * Evite: Repositório * Use: administrador, pessoas com permissões de administrador * Evite: Administração

Não use símbolos nem octicons que não são usados na interface do usuário do GitHub. * Use: clique em Arquivo e em Editar. * Evite: Clique em Arquivo > Editar.

Contas

Nomes de produtos e contas

Para evitar ambiguidade e confusão, não use nomes de produtos como adjetivos para descrever contas em nenhum de nossos produtos. Em vez disso, esclareça o tipo de conta e escolha frases mais claras que evitem a confusão entre contas e produtos. Ao falar sobre contas, refira-se apenas ao nome do produto quando necessário para remover a ambiguidade entre os produtos. Para saber mais sobre os tipos de contas disponíveis nos produtos do GitHub, confira Tipos de contas de GitHub. * Use: sua organização do GitHub Enterprise Cloud * Evite: sua conta do GitHub Enterprise Cloud * Evite: sua organização do GitHub Enterprise Server * Use: destaque seu trabalho no GitHub Enterprise Server enviando as contagens de contribuições para seu perfil do GitHub.com.

Contas de pessoas individuais do GitHub

Nós nos referimos a uma conta em que uma pessoa individual entra de várias maneiras, dependendo do contexto.

A menos que o conteúdo seja a administração de um produto empresarial, descreva a conta de uma pessoa individual do GitHub como uma "conta pessoal". Isso cria consistência com a interface do usuário e impede que os leitores fiquem confusos ao ver dois termos representarem a mesma coisa.

•         **Use:** Gerenciamento de lembretes agendados para a sua conta pessoal
  

•         **Evite:** como gerenciar lembretes agendados da sua conta de usuário
  

Contas de produtos corporativos

Com os produtos corporativos do GitHub, os administradores gerenciam uma conta empresarial. Uma conta empresarial pode ser proprietária de várias organizações. As contas de usuário das pessoas podem ser membros das organizações. Para obter mais informações, confira o artigo "Funções em uma empresa" de cada produto.

•         [GitHub Enterprise Cloud](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)
  

•           [GitHub Enterprise Server](/enterprise-server@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)
  

Se o leitor gerenciar uma conta empresarial e você estiver descrevendo as contas das pessoas que ele gerencia, use "conta de usuário". Isso se aplica aos produtos a seguir.

• GitHub Enterprise Cloud com os Enterprise Managed Users * Use: com os Enterprise Managed Users, você pode criar e gerenciar as contas de usuário dos membros corporativos. * Evite: com os Enterprise Managed Users, você pode criar e gerenciar as contas pessoais dos membros corporativos.
• GitHub Enterprise Server * Use: caso você precise assumir temporariamente uma conta de usuário… * Evite: se você precisar assumir temporariamente uma conta pessoal…

A documentação a seguir deve referenciar "contas de usuário".

• O produto Documentação do administrador da empresa
• Documentação de cobrança específica da empresa, como Cobrança do GitHub Enterprise
• Conteúdo em outros produtos destinados a um público-alvo administrativo, como Melhores práticas para proteger contas no produto "Código de segurança" ou Configurando uma avaliação do GitHub Enterprise Cloud no produto "Introdução"
• Conteúdo de API específico da empresa, como a documentação de referência da API REST do Pontos de extremidade da API REST para administração do GitHub Enterprise

Para as empresas no GitHub Enterprise Cloud que não usam os Enterprise Managed Users, use "conta pessoal" ao descrever os membros de organizações pertencentes à empresa.

•         **Use:** se você configurar o SSO do SAML, os membros da sua organização continuarão entrando nas respectivas contas pessoais do GitHub.com.
  

•         **Evite:** se você configurar o SSO do SAML, os membros da sua organização continuarão entrando nas respectivas contas de usuário do GitHub.com.
  

Em geral, a documentação que descreve o GitHub Enterprise Cloud sem os Enterprise Managed Users está na categoria Gerenciar o logon único SAML para sua organização.

Contas de pessoas para outros serviços

Quando você descreve a conta de uma pessoa para um serviço diferente do GitHub, como um provedor de integração ou de autenticação, use "conta de usuário".

Acrônimos

Escreva os acrônimos por extenso na primeira vez em que forem usados em um artigo, exceto em títulos ou cabeçalhos.

Aplicativos

Use "app" ou "aplicativo" no conteúdo geral. * Use: Publique e liste seu app no GitHub Marketplace

Use "aplicativo" ao referenciar os OAuth apps, pois eles não são um produto. * Use: registrar um OAuth app * Evite: registrar um OAuth App

Use "App" ao referenciar o GitHub Apps, pois ele é um produto. * Use: Registre um GitHub App

Os GitHub Apps e os OAuth apps consistem em duas partes: o registro do aplicativo e o código que faz com que o aplicativo faça algo.

• Para se referir apenas às configurações do GitHub App na interface do usuário do GitHub, use uma terminologia como "registrar" e "registro do GitHub App". * Use: Registre um GitHub App * Use: Atualizar o registro do GitHub App * Evite: criar um GitHub App * Evite: modificar um GitHub App

• Para se referir apenas ao código do aplicativo, use uma terminologia como "código do aplicativo". * Use: código para o seu aplicativo * Use: código do GitHub App * Use: código do seu app * Evite: seu GitHub App * Evite: seu OAuth app

• Para referenciar todo o aplicativo em conjunto (registro e código), refira-se a ele como um GitHub App ou OAuth app.

Os GitHub Apps podem ser instalados em contas de organização e de usuário. Para referenciar uma instalação do aplicativo, use "instalação do GitHub App em vez de "GitHub App".

Moeda

Ao se referir a dólares, centavos, valores de moeda ou ao usar o sinal de $, verifique se a moeda usada é definida mesmo se o valor for zero. Use o nome da moeda padrão ISO e o código de moeda padrão ISO sempre que possível.

Use letras minúsculas para nomes de moedas, mas coloque em maiúsculas a referência ao país ou à região. * Use: dólar dos EUA. * Evite: Dólar dos EUA, dólar $USD.

Use maiúsculas para códigos de moeda.

•           **Use:** USD.
  

Quando houver apenas uma referência em um artigo, use o nome da moeda sem um $ antes do valor. * Use:10 US dollars para uma só referência à moeda.

Quando um artigo contiver várias referências à mesma moeda, verifique se a primeira referência usa o nome da moeda sem um $ antes do valor e inclui o código de moeda entre parênteses após o nome da moeda.

Para as referências seguintes à moeda em um artigo ou quando apropriado (como quando o espaço é uma consideração ou quando vários valores são apresentados em uma tabela ou em uma lista), inclua o $ antes do valor e use o código de moeda padrão ISO após o valor. * Use:10 US dollars (USD) para a primeira referência e $0.25 USD para as referências seguintes. * Evite:$10 US dollars (USD), USD$0.25.

Quando a primeira referência for relacionada a centavos ou a um valor que não esteja em dólar, coloque em maiúsculas a referência ao país ou à região da moeda usada entre parênteses imediatamente após a primeira referência. As referências de moeda seguintes são tratadas usando as diretrizes acima.

•         **Use:**`99 cents (US currency)` para a primeira referência e `99 cents` para as referências seguintes.
  

•         **Evite:**`$0.99 (US currency)`, `$0.99 USD cents` e `USD$0.99 cents`.
  

Permissões

Uma permissão é a capacidade de executar uma ação específica. Por exemplo, a capacidade de excluir um problema é uma permissão.

Uma função é um conjunto de permissões que podem ser atribuídas a um usuário. As funções existem em níveis diferentes.

• Contas (por exemplo, proprietário da organização, gerente de cobrança de uma conta empresarial)
• Recursos (por exemplo, gravação em um repositório, administrador em um aviso de segurança)
• Equipes (por exemplo, mantenedor de equipes)

Em geral, o acesso de uma pessoa se refere a todas as habilidades que a pessoa tem em um contexto específico, independentemente de quais funções ou permissões individuais essas habilidades são provenientes.

Só use permissão ou função quando a distinção entre as duas for importante. Caso contrário, use acesso.

•         **Use:** para criar uma função de repositório personalizada, escolha uma função herdada e adicione permissões individuais.
  

•         **Use:** gerenciar o acesso da equipe ao repositório de sua organização
  

•         **Use:** se sua associação de equipe der a você um nível de acesso diferente do de sua função de proprietário da organização...
  

•         **Use:** pessoas com acesso de gravação podem…
  

•         **Evite:** pessoas com o acesso para gravação podem…
  

•         **Evite:** pessoas com a função de gravação podem…
  

•         **Evite:** pessoas com permissões de gravação podem…
  

•         **Evite:** pessoas com privilégios de gravação podem…
  

Ao especificar o acesso necessário para executar uma ação, refira-se apenas à função no mesmo nível da ação. Por exemplo, você precisa de acesso de administrador a um repositório, que é uma função de nível de repositório, para configurar ramificações protegidas. Você pode obter acesso de administrador em um repositório sendo um proprietário da organização, uma função no nível da organização, mas a função no nível do repositório é o que realmente controla sua capacidade de executar a ação, portanto, essa é a única função que deve ser mencionada.

•         **Use:** pessoas com acesso de gravação a um repositório podem fazer X para o repositório.
  

•         **Evite:** proprietários de organizações e pessoas com acesso de gravação podem fazer X no repositório.
  

Para obter mais informações sobre a escolha de palavras para declarações de permissões, consulte Conteúdo de um artigo do GitHub Docs no modelo de conteúdo.

Preposições

Evite terminar uma frase com uma preposição, a menos que a frase reescrita soe estranha ou muito formal.

Nomes de produtos

Confira a seção “Nomes de produtos” deste guia.

Termos a serem usados ou evitados

Escolha das palavras

Verbos ambíguos

Quando uma tarefa é necessária, ou uma opção tem preferência em relação a outra, evite usar verbos auxiliares modais ambíguos, como "pode", "poderia", "deve", "deveria" e "faria". Esses verbos podem ser interpretados tanto como um comando quanto como uma sugestão. Em vez disso, use verbos que indiquem claramente se a ação é obrigatória ou opcional. Se algo for uma opção ou sugestão, você pode usar esses verbos, desde que deixe claro que a ação é opcional.

•         **Use:** você pode decidir quais atalhos de teclado usar.
  

•         **Use:** use o comando `git clone` para clonar um repositório.
  

•         **Evite:** você pode usar o comando `git clone` para clonar um repositório.
  

•         **Evite:** você poderia excluir a ramificação.
  

Plurais invisíveis

Evite plurais invisíveis, que são palavras com um significado ambíguo, porque podem ser interpretadas como singulares ou plurais. Por exemplo, "recuperação de arquivo" pode se referir à recuperação de um único arquivo ou vários arquivos.

•         **Use:** depois que o arquivo for recuperado, selecione onde salvá-lo.
  

•         **Evite:** após recuperar o arquivo, selecione onde salvá-lo.
  

Substantivações

Evite substantivações, que são substantivos criados de verbos ou adjetivos. Substantivações podem estender as sentenças, tornando-as mais difíceis de entender e de traduzir.

•         **Use:** após a conclusão do fluxo de trabalho, o pacote ficará visível.
  

•         **Evite:** Após o fluxo de trabalho ser concluído, o pacote ficará visível.
  

Sequências de substantivos

Evite modificadores sequenciais (sequências de substantivos), que possam levar a traduções incorretas, porque as traduções podem não conseguir identificar qual palavra está modificando a outra. Você pode reformular a sequência de substantivos usando uma preposição. Se o uso de um modificador sequencial for indispensável, verifique se as informações de referência e o contexto estão claros para que os leitores e o tradutor possam entender o que está sendo modificado. * Use: configurações de origem padrão para repositórios públicos * Evite: configurações de origem padrão de repositório público

Substantivos e pronomes vagos

Se um pronome parecer se referir a mais de um antecedente, reformule a frase para deixar o antecedente claro ou substitua o pronome por um substantivo a fim de eliminar a ambiguidade.

•         **Use:** após fazer o commit final para seu branch e mesclar sua solicitação de pull, você pode excluir seu branch.
  

•         **Evite:** após fazer a confirmação final para sua ramificação e mesclar sua solicitação de pull, você pode excluí-lo.