Criar um LEIAME para seu repositório

  • Artigo

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

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

  • Usuários que só querem executar seu código.
  • Desenvolvedores que desejam compilar 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 tanto desenvolvedores quanto usuários.

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

Aqui estão alguns ótimos leiames que usam esse formato e falam com todos os três públicos, para referência e inspiração:

Criar uma introdução

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

Ajude seus usuários a começar

Oriente os usuários a colocar seu código em funcionamento em seu próprio sistema na próxima seção do seu leiame. Mantenha-se focado nas etapas essenciais para começar a usar seu código. Forneça links para as versões obrigatórias de todos os softwares necessários para que os usuários possam acessá-los facilmente. Se você tiver etapas de instalação complexas, documente-as fora do seu leiame e forneça links para elas.

Aponte onde obter a versão mais recente do seu código. Um instalador binário ou instruções sobre como usar seu código por meio de ferramentas de empacotamento é a melhor alternativa. Se o 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.

Forneça as etapas de compilação para os desenvolvedores

Use a próxima seção do seu leiame 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. Faça o seguinte:

  • 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 sem problemas.
  • Exiba as instruções de build densas ou complexas em uma página separada de sua documentação e forneça links a ela, se necessário.
  • Execute as instruções enquanto as escreve para verificar se as instruções funcionariam para um novo contribuidor.

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

Forneça os comandos para executar quaisquer casos de teste fornecidos com o código-fonte depois que o build for bem-sucedido. Os desenvolvedores dependem desses casos de teste para garantir que eles não danifiquem seu código à medida que fazem alterações. Bons casos de teste também servem como modelos que os desenvolvedores podem usar para criar seus próprios casos de teste ao adicionar novas funcionalidades.

Ajude os usuários a contribuir

A última seção do seu leiame ajuda usuários e desenvolvedores a se envolverem na comunicação de problemas e na sugestão de ideias para melhorar seu código. Os usuários devem estar vinculados a canais nos quais possam 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 programação/testagem e requisitos de solicitação de pull. Se você precisar de um contrato de colaboração para aceitar solicitações de pull ou impor um código de conduta à comunidade, esse processo deverá ser vinculado ou documentado nesta seção. Declare em qual licença o código é liberado e forneça o link para o texto completo da licença.