Contribuir com os repositórios de documentação do .NET

Agradecemos seu interesse em contribuir com a documentação do .NET.

Este documento trata do processo de contribuir com artigos que exemplos de código que são hospedados no site de documentação do .NET. As contribuições podem ser tão simples quanto correções de erro de digitação ou tão complexas quanto novos artigos.

O site de documentação do .NET é composto por diversos repositórios. Esses são apenas alguns deles:

• Artigos conceituais e snippets de código do .NET
• Exemplos e snippets de código
• Referência da API REST
• Referência do SDK do .NET Compiler Platform
• Referência de API do ML.NET

Diretrizes para contribuições

Agradecemos as contribuições da comunidade para a documentação. A seguinte lista mostra algumas regras gerais que você precisa ter em mente ao contribuir com a documentação do .NET:

• NÃO nos surpreenda com solicitações de pull grandes. Em vez disso, registre um problema e inicie uma discussão para que possamos concordar sobre o que fazer antes de você gastar muito tempo nisso.
• NÃO inclua um exemplo de código embutido em um artigo.
• USE um projeto de snippet com código a ser inserido no artigo.
• SIGA estas instruções e as diretrizes de tom e comunicação.
• FAZER: use o arquivo de modelo como o ponto de partida do seu trabalho.
• FAZER: crie um branch separado em seu fork antes de trabalhar nos artigos.
• SIGA o fluxo do GitHub.
• DIVULGUE em seu blog e Twitter (ou onde for) suas contribuições, se desejar.

Seguir estas diretrizes garantirá uma melhor experiência para você e para nós.

Processo de contribuição

Etapa 1: se você estiver interessado em escrever um novo conteúdo ou revisar detalhadamente o conteúdo existente, abra um problema descrevendo o que deseja fazer. O conteúdo dentro da pasta documentos é separado em seções organizadas que são refletidas no sumário. Defina onde o tópico será posicionado no TOC. Obter comentários sobre sua proposta.

-ou-

Escolha um problema existente e resolva-o. Você pode examinar nossa lista de problemas em aberto e se voluntariar para trabalhar naqueles em que tem interesse:

• Filtre pela etiqueta bom primeiro problema para que problemas menos complicados sejam exibidos primeiro.
• Filtre pela etiqueta preciso de ajuda para problemas apropriados para a contribuição da comunidade. Esses problemas geralmente exigem um contexto mínimo.
• Os colaboradores experientes podem resolver problemas de interesse.

Quando encontrar um problema, adicione um comentário a ele perguntando se está em aberto.

Depois de escolher uma tarefa para trabalhar, crie uma conta no GitHub e vá para a Etapa 2.

Etapa 2: faça o fork do /dotnet/docs repositório (ou qualquer outro para o qual você esteja contribuindo) conforme necessário e crie uma ramificação para suas alterações.

Para fazer pequenas alterações consulte Editar no navegador.

Etapa 3: fazer as alterações nesse novo branch.

Se for um novo tópico, você poderá usar esse arquivo de modelo como ponto de partida. Ele contém as diretrizes de escrita e também explica os metadados necessários para cada artigo, como informações do autor. Para obter mais informações sobre a sintaxe de Markdown usada no conteúdo do Microsoft Learn, consulte Referência de Markdown.

Navegue até a pasta que corresponde à localização do Sumário determinado para o seu artigo na Etapa 1. Essa pasta contém os arquivos Markdown para todos os artigos nesta seção. Se necessário, crie uma pasta para colocar os arquivos do seu conteúdo. O artigo principal desta seção chama-se index.md.

Para imagens e outros recursos estáticos, crie uma subpasta chamada mídia dentro da pasta que contém seu artigo, se ainda não houver. Dentro da pasta mídia, crie uma subpasta com o nome do artigo (exceto para o arquivo de índice). Para obter mais informações sobre onde posicionar os arquivos, consulte a seção Estrutura de pasta de exemplo.

Não inclua código embutido no artigo, a menos que você esteja demonstrando um constructo que não seja compilado. Em vez disso, use um projeto de snippets de código e inclua o código usando a extensão de código. Isso garante que seu exemplo de código seja validado pelo nosso sistema de CI.

Para snippets de código, crie uma subpasta chamada snippets dentro da pasta que contém seu artigo, caso ainda não exista. Dentro da pasta snippets, crie uma subpasta com o nome do artigo. Na maioria dos casos, você terá snippets de código para todas as três principais linguagens do .NET: C#, F# e Visual Basic. Nesse caso, crie subpastas chamadas csharp, fsharp e vb para cada um dos três projetos. Se você estiver criando um snippet para um artigo nas pastas docs/csharp, docs/fsharp ou docs/visual-basic, o snippet estará em apenas uma linguagem para que você possa omitir a subpasta de linguagem. Para obter mais informações sobre onde posicionar os arquivos, consulte a seção Estrutura de pasta de exemplo.

Os snippets de código são exemplos pequenos e focados de códigos que demonstram os conceitos abordados em um artigo. Programas maiores, destinados a download e exploração, devem estar localizados no repositório dotnet/samples. Exemplos completos são abordados na seção Contribuir com exemplos.

Etapa 4: envie um pull request (PR) do seu branch para o branch padrão.

Importante

A funcionalidade de automação de comentários não está disponível em nenhum dos repositórios de documentos do .NET no momento. Membros da equipe de documentos do .NET examinarão e mesclarão sua PR.

Cada PR normalmente deve tratar de um problema por vez, a menos que vários problemas estejam relacionados à mesma correção de PR. A PR pode modificar um ou vários arquivos. Se você está abordando várias correções em diferentes arquivos, é preferível usar PRs separadas.

Se a PR corrigir um problema existente, adicione a palavra-chave Fixes #Issue_Number à descrição da PR. Dessa forma, o problema se encerra automaticamente ao mesclar a PR. Para obter mais informações, consulte Vinculando uma solicitação de pull a um problema usando uma palavra-chave.

A equipe do .NET examinará a PR e informará se outras atualizações/alterações são necessárias para aprová-la.

Etapa 5: faça as atualizações necessárias no branch, conforme discutido com a equipe.

Os profissionais responsáveis pela manutenção mesclarão sua PR à ramificação padrão quando os comentários forem aplicados e sua alteração for aprovada.

Nós enviamos todas as confirmações por push regularmente da ramificação padrão para a ramificação ativa e, em seguida, você poderá ver sua contribuição ativa na documentação do .NET. Normalmente, publicamos diariamente durante dias úteis.

Estrutura de pasta de exemplo

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
          portability_report.png
        /shared ...
      /snippets
        /porting-overview
          /csharp
            porting.csproj
            porting-overview.cs
            Program.cs
          /fsharp
            porting.fsproj
            porting-overview.fs
            Program.fs
          /vb
            porting.vbproj
            porting-overview.vb
            Program.vb
        /shared
          /csharp ...
          /fsharp ...
          /vb ...

Observação

As pastas de idiomas em snippets de código não são necessárias na área de guia de idioma, em que apenas um idioma é assumido. Por exemplo, no guia do C#, supõe-se que todos os snippets são C#.

A estrutura mostrada acima inclui uma imagem, portability_report.png, e três projetos de código que incluem snippets de código incluídos no artigo porting-overview.md.

A pasta snippets/compartilhada é usada para snippets que podem abranger vários artigos dentro da mesma pasta pai, como a pasta porting no exemplo anterior. Use apenas a pasta compartilhada quando tiver um motivo específico para fazer isso, como o código XAML que é referenciado por vários artigos, mas que não pode ser compilado na pasta específica do artigo.

A mídia também pode ser compartilhada entre artigos quando esses artigos estão na mesma pasta pai, como a pasta porting no exemplo anterior. Essa pasta compartilhada deve ser evitada, se possível, e usada apenas quando fizer sentido. Por exemplo, pode fazer sentido compartilhar uma tela de carregamento comum para o aplicativo que está sendo demonstrado ou compartilhar diálogo do Visual Studio que são reutilizados em vários artigos.

Importante

Por razões históricas, muitos dos snippets incluídos são armazenados na pasta /samples no repositório dotnet/docs. Caso você esteja fazendo grandes alterações em um artigo, esses snippets deverão ser movidos para a nova estrutura. No entanto, não se preocupe em mover snippets para pequenas alterações.

Contribuir com as amostras

Fazemos a seguinte distinção para os códigos que dão suporte ao nosso conteúdo:

• Exemplos: os leitores podem baixar e executar as amostras. Todas as amostras devem ser aplicativos ou bibliotecas completos. Quando a amostra cria uma biblioteca, ela deve incluir testes de unidade ou um aplicativo que permita aos leitores executar o código. Frequentemente, eles usam mais de uma tecnologia, recurso ou kit de ferramentas. O arquivo readme.md de cada exemplo fará referência ao artigo, para que você possa ler mais sobre os conceitos abordados em cada exemplo.
• Snippets: ilustram um conceito ou tarefa menor. Eles são compilados, mas não são destinados a ser aplicativos completos. Eles devem ser executados corretamente, mas não são um aplicativo de exemplo para um cenário típico. Em vez disso, têm o objetivo de ter o menor tamanho possível para ilustrar um único conceito ou recurso. Eles não devem ter mais de uma tela de código.

Os exemplos são armazenados no repositório dotnet/samples. Estamos trabalhando para criar um modelo em que nossa estrutura de pastas de amostras corresponda à nossa estrutura de pastas de documentos. Os padrões que seguimos são:

• As pastas de nível superior correspondem às pastas de nível superior no repositório docs. Por exemplo, o repositório docs tem uma pasta machine-learning/tutorials, e as amostras para tutoriais de aprendizado por máquina estão na pasta samples/machine-learning/tutorials.

Além disso, todas as amostras nas pastas core e standard devem ser compiladas e executadas em todas as plataformas compatíveis com o .NET Core. Nosso sistema de build de CI força isso. A pasta de nível superior framework contém exemplos que só são compilados e validados no Windows.

Projetos de exemplo devem ser compilados e executados na maior gama de plataformas possível para o exemplo dado. Na prática, isso significa compilar aplicativos de console baseados em .NET Core quando possível. Exemplos específicos da Web ou de uma estrutura de interface do usuário devem adicionar essas estruturas conforme for necessário. Exemplos incluem aplicativos Web, aplicativos móveis, aplicativos do WPF ou WinForms e assim por diante.

Estamos trabalhando para ter um sistema de CI em vigor para todo o código. Quando fizer atualizações nos exemplos, certifique-se de que cada atualização faça parte de um projeto compilável. Idealmente, adicione testes para avaliar a correção dos exemplos também.

Cada amostra completa que você cria deve conter um arquivo readme.md. Esse arquivo deve conter uma breve descrição da amostra (um ou dois parágrafos). O readme.md deve informar aos leitores o que eles aprenderão ao explorar essa amostra. O arquivo readme.md também deve conter um link para o documento ativo no site de documentação do .NET. Para definir o local de mapeamento de determinado arquivo no repositório para esse site, substitua /docs no caminho do repositório por https://learn.microsoft.com/dotnet.

Seu tópico também conterá links para a amostra. Crie um link diretamente para a pasta da amostra no GitHub.

Escrever uma nova amostra

Exemplos são programas e bibliotecas completos e destinados a download. Eles podem ser pequenos no escopo, mas demonstram conceitos de uma forma que permita às pessoas explorar e experimentar por conta própria. As diretrizes para exemplos garantem que os leitores possam baixá-los e explorá-los. Examine os exemplos de PLINQ (Parallel LINQ) como exemplos de cada uma das diretrizes.

1. Seu exemplo deve fazer parte de um projeto compilável. Quando possível, os projetos devem ser compilados em todas as plataformas com suporte do .NET Core. São exceções exemplos que demonstram um recurso ou uma ferramenta específica de uma plataforma.

2. Sua amostra deve estar em conformidade com o estilo de código de runtime para manter a uniformidade.

   Além disso, damos preferência ao uso de métodos static em vez de métodos de instância ao demonstrar algo que não exige instanciar um novo objeto.

3. Seu exemplo deve incluir o tratamento de exceções adequado. Ele deve tratar de todas as exceções que têm probabilidade de ser geradas no contexto do exemplo. Por exemplo, um exemplo que chama o método Console.ReadLine para recuperar a entrada do usuário deve usar o tratamento de exceções adequado quando a cadeia de caracteres de entrada é passada como um argumento para um método. De forma semelhante, se o exemplo esperar que uma chamada de método falhe, a exceção resultante deverá ser tratada. Sempre trate das exceções específicas geradas pelo método, em vez de exceções de classe base como Exception ou SystemException.

Para criar um exemplo:

1. Registre um problema ou adicione um comentário a um problema existente no qual você está trabalhando.

2. Escreva o tópico que explica os conceitos demonstrados em seu exemplo (exemplo: docs/standard/linq/where-clause.md).

3. Escreva o exemplo (exemplo: WhereClause-Sample1.cs).

4. Crie um Program.cs com um ponto de entrada principal que chama seus exemplos. Se já houver um, adicione a chamada ao exemplo:

   public class Program
   {
       public void Main(string[] args)
       {
           WhereClause1.QuerySyntaxExample();
   
           // Add the method syntax as an example.
           WhereClause1.MethodSyntaxExample();
       }
   }
   

Você compila qualquer snippet ou exemplo do .NET usando a CLI do .NET, que pode ser instalada com o SDK do .NET. Para compilar e executar seu exemplo:

1. Vá até a pasta de exemplos e compile para verificar se há erros:

   dotnet build
   

2. Execute seu exemplo:

   dotnet run
   

3. Adicione um readme.md ao diretório raiz do exemplo.

   Ele deve incluir uma breve descrição do código e direcionar as pessoas ao artigo que faz referência ao exemplo. A parte superior do readme.md deve ter os metadados necessários para o navegador de exemplos. O bloco do cabeçalho deve conter os seguintes campos:

   ---
   name: "really cool sample"
   description: "Learn everything about this really cool sample."
   page_type: sample
   languages:
     - csharp
     - fsharp
     - vbnet
   products:
     - dotnet-core
     - dotnet
     - dotnet-standard
     - aspnet
     - aspnet-core
     - ef-core
   ---
   

   • A coleção languages deve incluir apenas as linguagens disponíveis para o seu exemplo.
   • A coleção products deve incluir apenas aqueles produtos relevantes para o seu exemplo.

Exceto quando observado, todos os exemplos são compilados na linha de comando de qualquer plataforma com suporte do .NET. Há alguns exemplos que são específicos do Visual Studio e requerem o Visual Studio 2017 ou posterior. Além disso, alguns exemplos mostram funcionalidades específicas de uma plataforma e exigirão a plataforma específica. Outros exemplos e snippets requerem o .NET Framework e serão executados em plataformas Windows, sendo que precisarão do Pacote do Desenvolvedor da versão de destino do Framework.

A experiência interativa em C#

Todos os snippets incluídos em um artigo usam uma tag de linguagem para indicar a linguagem do código-fonte. Snippets de código curtos em C# podem usar a tag de linguagem csharp-interactive para especificar um snippet em C# que é executado no navegador. (Snippets de código embutido usam a tag csharp-interactive, para snippets incluídos da origem, use a tag code-csharp-interactive.) Esses snippets de código exibem uma janela de código e uma janela de saída no artigo. A janela de saída exibe uma saída da execução do código interativo após o usuário ter executado o snippet.

A experiência do C# Interativo muda a forma como trabalhamos com snippets. Os visitantes podem executar o snippet para ver os resultados. Uma série de fatores ajuda a determinar se o snippet ou o texto correspondente deve incluir informações sobre a saída.

Quando exibir a saída esperada sem executar o snippet

• Artigos direcionados a iniciantes devem fornecer a saída para que os leitores possam comparar a saída do trabalho deles com a resposta esperada.
• Snippets em que a saída integral ao tópico deve exibir essa saída. Por exemplo, artigos sobre texto formatado devem mostrar o formato do texto sem executar o snippet.
• Quando o snippet o e a saída esperada forem curtos, considere mostrar a saída. Isso economiza um pouco de tempo.
• Artigos que explicam como a cultura atual ou a cultura invariável afetam a saída devem explicar a saída esperada. O Interactive REPL (Loop de Leitura-Avaliação-Impressão Interativo) é executado em um host baseado em Linux. A cultura padrão e a cultura invariável produzem uma saída diferente em computadores e sistemas operacionais diferentes. O artigo deve explicar a saída em sistemas Windows, Linux e Mac.

Quando excluir a saída esperada do snippet

• Os artigos em que o snippet gera uma saída maior não devem incluir isso em comentários. Isso esconde o código após a execução do snippet.
• Artigos em que o snippet demonstra um tópico, mas em que a saída não é fundamental para sua compreensão. Por exemplo, um código que executa uma consulta LINQ para explicar a sintaxe de consulta e, em seguida, exibir cada item da coleção de saída.

Observação

Você poderá observar que atualmente alguns dos tópicos não sequem todas as diretrizes especificadas aqui. Estamos trabalhando para atingir a consistência em todo o site. Verifique a lista de problemas em aberto que estamos acompanhando, no momento, para essa meta específica.

Contribuir com conteúdo que não seja em inglês

As contribuições para o conteúdo de MT (tradução automática) não estão sendo aceitas no momento. A fim de aprimorar a qualidade desse conteúdo, fizemos a transição para um mecanismo de MT neural. Aceitamos e incentivamos contribuições para o conteúdo de HT (tradução humana), que é usado para treinar esse mecanismo. Assim, ao longo do tempo, as contribuições para o conteúdo de HT aprimorarão a qualidade tanto de HT quanto de MT. Os tópicos de MT terão um aviso de isenção de responsabilidade informando que parte do tópico pode ser de MT, e o botão Editar não será exibido, pois a edição estará desabilitada.

Observação

A maioria das documentações localizadas não oferece a capacidade de editar ou fornecer comentários por meio do GitHub. Para fazer comentários sobre conteúdo localizado, use o formulário https://aka.ms/provide-feedback.

Contrato de licença do colaborador

Você deve assinar o CLA (Contrato de Licença de Contribuição) da .NET Foundation antes de sua solicitação de pull ser mesclada. Isso é um requisito a ser cumprido uma única vez para projetos na .NET Foundation. Você pode ler mais sobre CLAs (Contratos de Licença de Contribuição) na Wikipédia.

O contrato: CLA (Contrato de Licença de Distribuição) da .NET Foundation

Você não precisa assinar o contrato antecipadamente. Você pode clonar sua solicitação de pull, criar fork para ela e enviá-la como de costume. Quando sua solicitação de pull é criada, ela é classificada por um bot do CLA. Se a alteração for pequena (por exemplo, você corrigiu um erro de digitação), a PR receberá o rótulo cla-not-required. Caso contrário, ela é classificada como cla-required. Depois de você assinar o CLA, as solicitações de pull atual e todas as futuras são rotuladas como cla-signed.