Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022
Seu repositório 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 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 leiame no 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 obter mais documentação do seu leiame.
Aqui estão alguns ótimos readmes que usam esse formato e falam com todos os três públicos, para referência e inspiração:
Pré-requisitos
| Categoria | Requirements |
|---|---|
| Acesso ao Projeto | Membro de um projeto. |
| Permissões | - Exibir código em projetos privados: pelo menos acesso básico . - Clonar ou contribuir para o código em projetos privados: membro do grupo de segurança Colaboradores ou permissões correspondentes no projeto. - Definir permissões de branch ou repositório: gerenciar permissões de permissões para o branch ou repositório. - Alterar o branch padrão: editar permissões de políticas para o repositório. - Importar um repositório: membro do grupo de segurança Administradores do Projeto ou da permissão Criar repositório no nível do projeto do Git definida como Permitir. Para obter mais informações, consulte Definir permissões do Repositório do Git. |
| Serviços | Repositórios habilitados. |
| Ferramentas | Optional. Use comandos az repos : CLI do Azure DevOps. |
Observação
Em projetos públicos, os usuários com acesso ao Stakeholder têm acesso total ao Azure Repos, incluindo exibição, clonagem e contribuição para o código.
| Categoria | Requirements |
|---|---|
| Acesso ao Projeto | Membro de um projeto. |
| Permissões | - Exibir código: pelo menos acesso básico . - Clonar ou contribuir com o código: membro do grupo de segurança Colaboradores ou permissões correspondentes no projeto. |
| Serviços | Repositórios habilitados. |
Criar uma introdução
Inicie seu leiame com uma breve explicação descrevendo seu projeto. Adicione uma captura de tela ou GIF animado na 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 dele. Aplicativos e ferramentas executados somente em plataformas específicas devem ter as versões do sistema operacional com suporte anotadas nesta seção do leiame.
Ajudar os 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. Vincule-se às versões necessárias de qualquer software de pré-requisito para que os usuários possam acessá-los facilmente. Se você tiver etapas de instalação complexas, documente-as fora do seu leiame e vincule-as a elas.
Aponte onde obter a versão mais recente do código. Um instalador binário ou instruções sobre como usar seu código por meio de ferramentas de empacotamento é melhor. Se o projeto for uma biblioteca ou uma interface para uma API, coloque um snippet de código mostrando o uso básico e mostre a saída de exemplo para o código nesse snippet.
Fornecer etapas de build para 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 documentar as etapas para configurá-las para obter uma compilação limpa.
- Divida instruções de build densas ou complexas em uma página separada em sua documentação e vincule-as a ela, se necessário.
- Execute as instruções enquanto as escreve para verificar se as instruções funcionariam para um novo colaborador.
Lembre-se de que o desenvolvedor que depende dessas 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 o build for bem-sucedido. Os desenvolvedores se baseiam nesses casos de teste para garantir que eles não quebrem seu código à medida que 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.
Ajudar os usuários a contribuir
A última seção do seu leiame ajuda usuários e desenvolvedores a se envolverem em relatar problemas e sugerir ideias para melhorar seu código. Os usuários devem estar vinculados a canais em que 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 de pull. Se você precisar de um contrato de colaborador para aceitar solicitações de pull ou impor um código de conduta da comunidade, esse processo deverá ser vinculado ou documentado nesta seção. Declarar em qual licença o código é liberado e vincular ao texto completo da licença.