Contribua para os repositórios de documentação do .NET

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

Este documento aborda o processo de contribuição para os artigos e exemplos de código alojados no site de documentação do .NET. As contribuições podem ser tão simples como a correção de erros de escrita ou tão complexas como a criação de novos artigos.

O site de documentação do .NET é criado a partir de vários repositórios. Estes são apenas alguns deles:

• Artigos conceptuais do .NET e fragmentos de código
• Exemplos e fragmentos de código
• Referência da API .NET
• Referência do SDK de Plataforma de Compilador .NET
• Referência da API ML.NET

Diretrizes para as contribuições

Apreciamos as contribuições da comunidade para a documentação. A lista a seguir mostra algumas regras orientadoras que você deve ter em mente ao contribuir com a documentação do .NET:

• NÃO nos envie pedidos pull de grandes dimensões. Em vez disso, submeta um problema e inicie um debate para que possamos decidir o que fazer antes que invista muito tempo na tarefa.
• NÃO inclua código de exemplo embutido em um artigo.
• USE um projeto de snippet com código a ser incorporado no artigo.
• SIGA estas instruções e diretrizes de tom e registo.
• UTILIZE o ficheiro de modelo como ponto de partida para o seu trabalho.
• CRIE um ramo separado no seu fork antes de trabalhar nos artigos.
• SIGA o fluxo do GitHub.
• CRIE publicações de blogue e tweets (por exemplo) sobre as suas contribuições, se quiser!

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

Processo de contribuição

Etapa 1: se você estiver interessado em escrever um novo conteúdo ou em revisar completamente o conteúdo existente, abra um problema descrevendo o que você deseja fazer. O conteúdo dentro da pasta docs é organizado em seções que são refletidas no sumário (TOC). Defina a localização do tópico no Índice. Obtenha feedback sobre a sua proposta.

-or-

Escolha um problema já existente e resolva-o. Pode ver a nossa lista de problemas abertos e voluntariar-se para trabalhar naqueles em que tiver interesse:

• Filtre pelo rótulo de boa primeira edição para, bem, boas primeiras edições.
• Filtre pelo rótulo de ajuda desejada para questões apropriadas para a contribuição da comunidade. Normalmente, estes problemas requerem contexto mínimo.
• Os contribuidores experientes podem resolver quaisquer problemas do seu interesse.

Quando encontrar um problema para trabalhar, adicione um comentário para perguntar se está aberto.

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

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

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

Passo 3: faça as alterações neste novo ramo.

Caso se trate de um novo tópico, pode utilizar este ficheiro de modelo como ponto de partida. Contém as diretrizes de escrita e também indica quais os metadados necessários para cada artigo, como as informações do autor. Para obter mais informações sobre a sintaxe Markdown usada no conteúdo do Microsoft Learn, consulte Markdown reference.

Navegue até a pasta que corresponde ao local do sumário determinado para o seu artigo na Etapa 1. Essa pasta contém os ficheiros de Markdown para todos os artigos nessa secção. Se for necessário, crie uma nova pasta para colocar os ficheiros dos seus conteúdos. O artigo principal dessa secção é denominado index.md.

Para imagens e outros recursos estáticos, crie uma subpasta denominada media dentro da pasta que contém o seu artigo (caso ainda não exista uma pasta com esse nome). Dentro da pasta media, crie uma subpasta com o nome do artigo (exceto para o ficheiro index). Para obter mais informações sobre onde colocar seus arquivos, consulte a seção Exemplo de estrutura de pastas.

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

Para code snippets (fragmentos de código), crie uma subpasta denominada snippets (fragmentos) dentro da pasta que contém o seu artigo (caso ainda não exista uma pasta com esse nome). Na pasta snippets (fragmentos), crie uma subpasta com o nome do artigo. Na maioria dos casos, terá fragmentos de código para as três principais linguagens .NET, C#, F# e Visual Basic. Nesse caso, crie subpastas denominadas csharp, fsharp e vb para cada um dos três projetos. Se estiver a criar um fragmento para um artigo em docs/csharp, docs/fsharp ou pastas docs/visual-basic, o fragmento ficará em apenas uma linguagem, pelo que pode omitir a subpasta de linguagem. Para obter mais informações sobre onde colocar seus arquivos, consulte a seção Exemplo de estrutura de pastas.

Os fragmentos de código são exemplos de código pequenos e direcionados que demonstram os conceitos abrangidos por um artigo. Os programas maiores, destinados à transferência e exploração, devem estar localizados no repositório dotnet/samples. Os exemplos completos são abrangidos na secção Contribuir para exemplos.

Etapa 4: envie uma solicitação pull (PR) da sua filial para a ramificação padrão.

Importante

Neste momento, a funcionalidade automatização de comentários não está disponível em nenhum dos repositórios de documentação do .NET. Os membros da equipa da documentação do .NET irão rever e intercalar o seu pedido Pull.

Cada RP geralmente deve abordar um problema de cada vez, a menos que vários problemas estejam relacionados à mesma correção de RP. O pedido Pull pode modificar um ou múltiplos ficheiros. Se estiver a resolver múltiplos problemas em ficheiros diferentes, recomendamos pedidos Pull separados.

Se o seu PR corrigir um problema existente, adicione a Fixes #Issue_Number palavra-chave à descrição do PR. Dessa forma, o problema será fechado automaticamente quando o pedido Pull for intercalado. Para obter mais informações, consulte Vinculando uma solicitação pull a um problema usando uma palavra-chave.

A equipa do .NET irá rever o seu pedido Pull e dizer-lhe se existem outras atualizações/alterações necessárias para o mesmo ser aprovado.

Passo 5: faça as atualizações necessárias ao seu ramo, conforme debatido com a equipa.

Os mantenedores mesclarão seu PR na ramificação padrão assim que o feedback for aplicado e sua alteração for aprovada.

Enviamos regularmente todas as confirmações da ramificação padrão para a ramificação ativa e, em seguida, você poderá ver sua contribuição ao vivo na documentação do .NET. Normalmente, fazemos publicações todos os dias, durante a semana.

Exemplo de estrutura de pasta

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

Nota

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

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

Os trechos/pasta compartilhada são usados para trechos que podem abranger vários artigos dentro da mesma pasta pai, como a pasta de portabilidade no exemplo anterior. Use a pasta compartilhada somente quando tiver um motivo específico para fazê-lo, como código XAML referenciado por vários artigos, mas que não pode compilar 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 de portabilidade 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 caixas de diálogo do Visual Studio que são reutilizadas em vários artigos.

Importante

Por razões de histórico, muitos dos fragmentos incluídos são armazenados na pasta /samples no repositório dotnet/docs. Se estiver a fazer grandes alterações a um artigo, esses fragmentos devem ser movidos para a nova estrutura. No entanto, não se preocupe em mover trechos para pequenas alterações.

Contribuir para os exemplos

Fazemos a seguinte distinção do código que suporta o nosso conteúdo:

• Exemplos: os leitores podem transferir e executar os exemplos. Todos os exemplos devem ser bibliotecas ou aplicações completas. No local onde o exemplo cria uma biblioteca, deverá incluir testes de unidades ou uma aplicação que permita que os leitores executem o código. Geralmente, utilizam mais do que uma tecnologia, funcionalidade ou toolkit. O ficheiro readme.md de cada exemplo irá fazer referência ao artigo, para que possa ler mais sobre os conceitos abordados em cada exemplo.
• Fragmentos de código: ilustram uma tarefa ou conceito menor. Criam compilações, mas não se destinam a ser aplicações completas. Devem ser executados corretamente, mas não são uma aplicação de exemplo para um cenário típico. Em vez disso, são concebidos para ser o mais pequenos possível de forma a ilustrar um único conceito ou funcionalidade. Não deve haver mais do que um ecrã de código.

Os exemplos estão armazenados no repositório dotnet/samples. Estamos a trabalhar no sentido de criar um modelo em que a estrutura de pastas dos exemplos corresponda à estrutura de pastas da documentação. Eis as normas que seguimos:

• 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 os exemplos de tutoriais de aprendizagem automática estão na pasta samples/machine-learning/tutorials.

Além disso, todos os exemplos nas pastas core e standard devem ser compilados e executados em todas as plataformas suportadas pelo .NET Core. O nosso sistema de compilação de CI irá impor esse processo. A pasta framework de nível superior contém exemplos que só podem ser criados e validados no Windows.

Os projetos de exemplo devem ser compilados e executados no maior número de plataformas possível para o exemplo indicado. Na prática, isto significa compilar aplicações de consola baseadas no .NET Core sempre que possível. Os exemplos que sejam específicos para a Web ou para um framework de IU devem adicionar essas ferramentas conforme necessário. Os exemplos incluem aplicações Web, aplicações móveis, aplicações WinForms ou WPF, etc.

Estamos a trabalhar para desenvolver um sistema de CI para todo o código. Quando atualizar exemplos, certifique-se de que cada atualização pertence a um projeto compilável. Idealmente, também deve adicionar testes para a correção de exemplos.

Cada exemplo completo que criar deve conter um ficheiro readme.md. Este ficheiro deve conter uma breve descrição do exemplo (um ou dois parágrafos). O seu ficheiro readme.md deve informar os leitores sobre o que irão aprender ao explorar o exemplo. O ficheiro readme.md também deve conter uma ligação para o documento publicado no site da documentação do .NET. Para determinar o local onde um determinado ficheiro no repositório mapeia a esse site, substitua /docs no caminho do repositório por https://learn.microsoft.com/dotnet.

O seu tópico também irá conter ligações para o exemplo. Crie ligações diretas para a pasta do exemplo no GitHub.

Escrever um novo exemplo

Os exemplos são programas e bibliotecas completos destinados a serem transferidos. Podem ser de pequeno âmbito, mas demonstram conceitos de uma forma que permite às pessoas explorar e experimentar por si próprias. As diretrizes para os exemplos garantem que os leitores podem transferir e explorar. Examine os exemplos Parallel LINQ (PLINQ) como um exemplo de cada uma das diretrizes.

1. O seu exemplo tem de pertencer a um projeto compilável. Sempre que possível, os projetos devem ser compilados em todas as plataformas suportadas pelo .NET Core. As exceções a esta regra são os exemplos que apresentam uma funcionalidade ou ferramenta específica para uma plataforma.

2. Seu exemplo deve estar em conformidade com o estilo de codificação de tempo de execução para manter a consistência.

   Além disso, a utilização de métodos static é preferencial, em vez de métodos instance, ao demonstrar um exemplo que não precise de instanciar um novo objeto.

3. O seu exemplo deve incluir o processamento de exceções adequado. Deve processar todas as exceções que possam ser emitidas no contexto do exemplo. Por exemplo, um exemplo que chame o método Console.ReadLine para obter dados introduzidos pelos utilizadores deverá utilizar o processamento de exceções adequado quando a cadeia de entrada for passada como um argumento para um método. Da mesma forma, se o seu exemplo esperar que uma chamada do método falhe, a exceção resultante tem de ser processada. Processe sempre as exceções específicas emitidas pelo método, exceto as exceções da classe base, como Exception ou SystemException.

Para criar um exemplo:

1. Crie um problema ou adicione um comentário a um problema existente no qual esteja a trabalhar.

2. Escreva um tópico que explique os conceitos demonstrados no seu exemplo (exemplo: docs/standard/linq/where-clause.md).

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

4. Crie um Program.cs com um ponto de entrada Main que chame os seus exemplos. Se já existir um, adicione a chamada ao seu exemplo:

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

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

1. Aceda à pasta do exemplo e compile para verificar se existem erros:

   dotnet build
   

2. Execute o seu exemplo:

   dotnet run
   

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

   Este ficheiro deve incluir uma breve descrição do código e encaminhar as pessoas para o artigo que faz referência ao exemplo. A parte superior de readme.md tem de ter os metadados necessários para o browser de exemplos. O bloco de 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 os produtos relevantes para o seu exemplo.

Exceto onde indicado, todos os exemplos são compilados a partir da linha de comando em qualquer plataforma suportada pelo .NET. Existem alguns exemplos específicos ao Visual Studio que necessitam do Visual Studio 2017 ou posterior. Além disso, alguns exemplos apresentam funcionalidades de plataformas específicas, que necessitam de uma plataforma específica. Outros exemplos e fragmentos de código necessitam do .NET Framework, serão executados em plataformas Windows e necessitarão do Developer Pack relativo à versão do Framework de destino.

A experiência de C# interativa

Todos os trechos incluídos em um artigo usam uma marca de idioma para indicar o idioma de origem. Trechos de código curto em C# podem usar a csharp-interactive marca de idioma para especificar um trecho de C# que é executado no navegador. (Trechos de código embutidos usam a csharp-interactive tag , para trechos incluídos da fonte, use a code-csharp-interactive tag .) Esses trechos de código exibem uma janela de código e uma janela de saída no artigo. A janela de saída exibe qualquer saída da execução do código interativo depois que o usuário executa o trecho.

A experiência interativa em C# muda a forma como trabalhamos com trechos. Os visitantes podem executar o trecho para ver os resultados. Vários fatores ajudam a determinar se o trecho ou o texto correspondente deve incluir informações sobre a saída.

Quando exibir a saída esperada sem executar o trecho

• Os artigos destinados a principiantes devem fornecer a saída, para que os leitores possam comparar a saída do respetivo trabalho com a resposta esperada.
• Trechos em que a saída é parte integrante do tópico devem exibir essa saída. Por exemplo, artigos em texto formatado devem mostrar o formato de texto sem executar o trecho.
• Quando o trecho e a saída esperada forem curtos, considere mostrar a saída. Isso irá poupar algum tempo.
• Os artigos que explicam como a cultura atual ou a cultura invariável afetam a saída devem indicar a saída esperada. A linguagem interativa REPL (Read Evaluate Print Loop) é executada num anfitrião baseado em Linux. A cultura predefinida e a cultura invariável produzem saídas diferentes em computadores e sistemas operativos diferentes. O artigo deve indicar a saída em sistemas Windows, Linux e Mac.

Quando excluir a saída esperada do trecho

• Os artigos em que o trecho gera uma saída maior não devem incluir isso nos comentários. Ele obscurece o código uma vez que o trecho tenha sido executado.
• Artigos em que o trecho demonstra um tópico, mas a saída não é essencial para entendê-lo. Por exemplo, o código executado numa consulta LINQ para explicar a sintaxe da consulta e, em seguida, apresentar todos os itens na coleção de saída.

Nota

Poderá reparar que atualmente alguns tópicos não seguem todas as diretrizes especificadas neste artigo. Estamos a trabalhar para eliminar as inconsistências em todo o site. Veja a lista de problemas abertos que estamos a monitorizar para esse propósito específico.

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

Atualmente, não são aceites contribuições para os conteúdos traduzidos automaticamente (TA). Num esforço de melhorar a qualidade dos conteúdos traduzidos automaticamente, fizemos a transição para um motor de TA neural. Aceitamos e incentivamos as contribuições para os conteúdos traduzidos por humanos (TH), que são utilizadas para treinar o motor de TA neural. Assim, ao longo do tempo, as contribuições para os conteúdos de TH melhorarão a qualidade de TH e TA. Os tópicos de TA terão um texto de exclusão de responsabilidade a informar que parte do tópico poderá ter sido traduzido por TA e o botão Edit (Editar) não será apresentado, uma vez que a edição está desativada.

Nota

A maioria da documentação localizada não oferece a capacidade de editar ou fornecer feedback através do GitHub. Para fornecer comentários sobre o conteúdo localizado, use o https://aka.ms/provide-feedback formulário.

Contrato de licença de contribuidor

Tem de assinar o .NET Foundation Contribution License Agreement (CLA) (Contrato de Licença de Contribuição [CLA] do .NET Foundation) antes de o seu pedido Pull ser intercalado. Este é um requisito único para os projetos no .NET Foundation. Pode ler mais sobre Contribution License Agreements (CLA) (Contratos de Licença de Contribuição [CLA]) na Wikipédia.

O contrato: .NET Foundation Contributor License Agreement (CLA)

Não tem de assinar o contrato previamente. Pode clonar, criar um fork e submeter o seu pedido Pull normalmente. Quando o seu pedido Pull for criado, será classificado por um bot CLA. Se a alteração for pequena (por exemplo, a correção de um erro ortográfico), o pedido Pull será identificado com a etiqueta cla-not-required. Caso contrário, será identificado com a etiqueta cla-required. Quando assinar o CLA, os pedidos Pull atuais e todos os pedidos Pull futuros serão identificados com a etiqueta cla-signed.