Nota
O acesso a esta página requer autorização. Podes tentar iniciar sessão ou mudar de diretório.
O acesso a esta página requer autorização. Podes tentar mudar de diretório.
Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022
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 dirigir-se aos 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:
Pré-requisitos
| Categoria | Requerimentos |
|---|---|
| Acesso ao projeto | Membro de um projeto . |
| Permissões | - Ver código em projetos privados: Acesso pelo menos Básico. - Clone ou contribua para o código em projetos privados: Membro do grupo de segurança Contributors ou permissões correspondentes no projeto. - Definir permissões de ramo ou repositório: Gerir permissões para o ramo ou repositório. - Alterar ramificação padrão: Editar políticas e permissões para o repositório. - Importar um repositório: Membro do grupo de segurança Administradores de Projeto ou com permissão de Criar repositório ao nível do projeto Git definida como Permitir. Para obter mais informações, consulte Definir permissões do repositório Git. |
| Serviços | Repos ativado. |
| Ferramentas | Opcional. Utilize os comandos az repos: Azure DevOps CLI. |
Observação
Em projetos públicos, os usuários com acesso Partes Interessadas têm acesso total aos repositórios do Azure, incluindo visualização, clonagem e contribuição para o código.
| Categoria | Requerimentos |
|---|---|
| Acesso ao projeto | Membro de um projeto . |
| Permissões | - Visualização de código: Pelo menos acesso básico. - Clone ou contribua para o código: Membro do grupo de segurança Contributors ou com permissões correspondentes no projeto. |
| Serviços | Repos ativado. |
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 tiver etapas de configuração complexas, documente-as fora do seu README e faça uma ligação para eles.
Indique onde obter a versão mais recente do seu código. Um instalador binário ou instruções sobre como usar o seu código por meio de ferramentas de empacotamento é o 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. 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 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.