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 | Servidor Azure DevOps | Azure DevOps Server 2022
Seu repositório Git deve ter um arquivo README para que os visualizadores saibam o que seu código faz e como eles podem começar a usá-lo. Seu arquivo README deve falar com os seguintes públicos-alvo:
- Usuários que desejam 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 arquivo README 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 para mais documentação do arquivo README.
Aqui estão alguns arquivos README que usam esse formato e falam com todos os três públicos. Use-os 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 com 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 são as permissões para o branch ou repositório. - Alterar o branch padrão: As políticas de edição são permissões 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. |
| Tools | Optional. Use az repos os comandos: 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 | - Visualizar 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 o arquivo README com uma breve explicação que descreve 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 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 arquivo README.
Ajudar os usuários a começar
Na próxima seção do arquivo README, guie os usuários para colocar seu código em funcionamento em seu próprio sistema. 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á-las facilmente. Se você tiver etapas de instalação complexas, documente essas etapas fora do arquivo README e vincule-as a elas.
Diga aos leitores onde obter a versão mais recente. Forneça um dos seguintes itens:
- Um link para um instalador binário ou pacote predefinido.
- Instruções de instalação usando um gerenciador de pacotes (por exemplo, npm install, pip install ou dotnet add package).
Se o projeto for uma biblioteca ou um wrapper de API, inclua um snippet de código mínimo que mostra o uso básico, seguido pela saída esperada. Essas informações ajudam os leitores a verificar a configuração e a entender o que a biblioteca faz rapidamente.
Fornecer etapas de build para desenvolvedores
Use a próxima seção do arquivo README para mostrar aos desenvolvedores como criar seu código a partir de um clone novo do repositório e executar todos os testes incluídos. Siga as seguintes etapas:
- 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 à medida que as escreve para verificar se são eficazes para um novo colaborador.
Lembre-se de que você pode ser o desenvolvedor que depende dessas instruções depois de não trabalhar em um projeto por algum tempo.
Inclua 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 quando adicionam novas funcionalidades.
Ajudar os usuários a contribuir
A última seção do arquivo README 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. Declare em qual licença o código é liberado e vincule-se ao texto completo da licença.