Partilhar via

Criar um README para o repositório

  • Artigo

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

Seu repositório Git deve ter um arquivo readme para que os espectadores saibam o que seu código faz e como eles podem começar a usá-lo. O seu readme deve falar para os seguintes públicos:

  • Usuários que querem apenas executar seu código.
  • Desenvolvedores que desejam criar e testar seu código. Os desenvolvedores também são usuários.
  • Colaboradores que desejam enviar alterações ao seu código. Os colaboradores são desenvolvedores e usuários.

Escreva seu readme em Markdown em vez de texto sem formatação. O Markdown facilita a formatação de texto, a inclusão de imagens e o link, conforme necessário, para mais documentação do seu readme.

Aqui estão algumas ótimas leituras que usam este formato e falam com os três públicos, para referência e inspiração:

Criar uma introdução

Comece o seu readme com uma breve explicação descrevendo o seu projeto. Adicione uma captura de tela ou GIF animado em sua introdução se seu projeto tiver uma interface de usuário. Se o seu código depende de outro aplicativo ou biblioteca, certifique-se de declarar essas dependências na introdução ou logo abaixo dela. Aplicativos e ferramentas que são executados apenas em plataformas específicas devem ter as versões suportadas do sistema operacional indicadas nesta seção do readme.

Ajude seus usuários a começar

Oriente os usuários através da colocação do seu código em funcionamento em seu próprio sistema na próxima seção do seu readme. Mantenha-se focado nas etapas essenciais para começar a usar seu código. Link para as versões necessárias de qualquer software de pré-requisito para que os usuários possam acessá-los facilmente. Se você tiver etapas de configuração complexas, documente aquelas fora do seu Leiame e vincule-as a elas.

Indique onde obter a versão mais recente do seu código. Um instalador binário ou instruções sobre como usar seu código através de ferramentas de empacotamento é melhor. Se o seu projeto for uma biblioteca ou uma interface para uma API, coloque um trecho de código mostrando o uso básico e mostre a saída de exemplo para o código nesse trecho.

Fornecer etapas de compilação para desenvolvedores

Use a próxima seção do seu readme para mostrar aos desenvolvedores como criar seu código a partir de um novo clone do repositório e executar todos os testes incluídos. Efetue o seguinte procedimento:

  • Forneça detalhes sobre as ferramentas necessárias para criar o código e documente as etapas para configurá-las para obter uma compilação limpa.
  • Divida instruções de construção densas ou complexas em uma página separada em sua documentação e crie um link para ela, se necessário.
  • Percorra as instruções enquanto as escreve para verificar se as instruções funcionariam para um novo colaborador.

Lembre-se, o desenvolvedor que confia nessas instruções pode ser você depois de não trabalhar em um projeto por algum tempo.

Forneça os comandos para executar quaisquer casos de teste fornecidos com o código-fonte depois que a compilação for bem-sucedida. Os desenvolvedores se apoiam nesses casos de teste para garantir que eles não quebrem seu código enquanto fazem alterações. Bons casos de teste também servem como exemplos que os desenvolvedores podem usar para criar seus próprios casos de teste ao adicionar novas funcionalidades.

Ajude os utilizadores a contribuir

A última seção do seu readme ajuda os usuários e desenvolvedores a se envolverem na geração de relatórios de problemas e sugerirem ideias para melhorar seu código. Os usuários devem ser vinculados a canais onde podem abrir bugs, solicitar recursos ou obter ajuda usando seu código.

Os desenvolvedores precisam saber quais regras precisam seguir para contribuir com alterações, como diretrizes de codificação/teste e requisitos de solicitação pull. Se você precisar de um contrato de colaborador para aceitar solicitações pull ou aplicar um código de conduta da comunidade, esse processo deve ser vinculado ou documentado nesta seção. Indique a licença sob a qual o código é liberado e vincule-o ao texto completo da licença.