Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022
O teu repositório Git deve ter um ficheiro README para que os visualizadores saibam o que o teu código faz e como podem começar a usá-lo. O seu ficheiro README deve dirigir-se aos seguintes públicos:
- Utilizadores que querem executar o seu código.
- Desenvolvedores que querem construir e testar o teu código. Os desenvolvedores também são usuários.
- Colaboradores que querem submeter alterações ao seu código. Os colaboradores são desenvolvedores e usuários.
Escreve o teu ficheiro README em Markdown em vez de texto simples. O Markdown facilita a formatação de texto, a inclusão de imagens e o link para mais documentação a partir do seu ficheiro README.
Aqui estão alguns ficheiros README que utilizam este formato e falam aos três públicos. Use-os como 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. - Clonar ou contribuir para código em projetos privados: Membro do grupo de segurança Contributors ou permissões equivalentes no projeto. - Definir permissões de branch ou repositório: As permissões de gestão são permissões para o branch ou repositório. - Alterar ramo predefinido: 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 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. |
| Tools | Opcional. Use az repos comandos: 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. |
Crie uma introdução
Comece o seu ficheiro README com uma breve explicação que descreva o seu projeto. Adiciona uma captura de ecrã ou um GIF animado na tua introdução se o teu projeto tiver uma interface de utilizador. Se o teu código depende de outra aplicação ou biblioteca, certifica-te de indicar essas dependências na introdução ou logo abaixo. Aplicações e ferramentas que funcionam apenas em plataformas específicas devem ter as versões suportadas do sistema operativo indicadas nesta secção do ficheiro README.
Ajude seus usuários a começar
Na secção seguinte do seu ficheiro README, oriente os utilizadores para pôr o seu código a funcionar no seu próprio sistema. Mantenha-se focado nas etapas essenciais para começar a usar seu código. Forneça ligação às versões necessárias de qualquer software pré-requisito para que os utilizadores possam aceder facilmente. Se tiveres passos de configuração complexos, documenta esses passos fora do teu ficheiro README e faz o link para eles.
Diga aos leitores onde encontrar o lançamento mais recente. Forneça um dos seguintes itens:
- Um link para um instalador binário ou pacote pré-construído.
- Instruções de instalação usando um gestor de pacotes (por exemplo, npm install, pip install ou dotnet add package).
Se o seu projeto for uma biblioteca ou um wrapper de API, inclua um excerto mínimo de código que mostre o uso básico, seguido da saída esperada. Esta informação ajuda os leitores a verificar a sua configuração e a perceber rapidamente o que a biblioteca faz.
Fornecer etapas de compilação para desenvolvedores
Use a secção seguinte do seu ficheiro README para mostrar aos programadores como construir o seu código a partir de um clone novo do repositório e executar quaisquer testes incluídos. Efetue os seguintes passos:
- 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 funcionam para um novo colaborador.
Lembre-se, pode ser o programador que depende destas instruções depois de algum tempo sem trabalhar num projeto.
Inclua os comandos para executar quaisquer casos de teste fornecidos com o código-fonte após o sucesso da compilação. 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 programadores podem usar para construir os seus próprios casos de teste quando adicionam novas funcionalidades.
Ajude os utilizadores a contribuir
A última secção do seu ficheiro README ajuda utilizadores e programadores a envolverem-se na reportagem de problemas e a sugerir ideias para melhorar o 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 sob que licença o código foi divulgado e faça o link para o texto completo da licença.