Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022
Votre dépôt Git doit avoir un fichier README afin que les visionneuses sachent ce que fait votre code et comment ils peuvent commencer à l’utiliser. Votre fichier README doit parler aux audiences suivantes :
- Utilisateurs qui souhaitent exécuter votre code.
- Développeurs qui souhaitent générer et tester votre code. Les développeurs sont également des utilisateurs.
- Contributeurs qui souhaitent envoyer des modifications à votre code. Les contributeurs sont des développeurs et des utilisateurs.
Écrivez votre fichier README dans Markdown au lieu de texte brut. Markdown permet de mettre en forme facilement du texte, d’inclure des images et de créer un lien vers d’autres documents à partir de votre fichier README.
Voici quelques fichiers README qui utilisent ce format et parlent aux trois audiences. Utilisez-les pour référencer et inspirer :
Prerequisites
| Catégorie | Spécifications |
|---|---|
| Accès au projet | Membre d’un projet. |
| Permissions | - Afficher le code dans des projets privés : au moins un accès niveau de base. - Clonez ou contribuez au code de projets privés : membre du groupe de sécurité "Contributeurs" ou disposant des autorisations correspondantes dans le projet. - Définir des autorisations de branche ou de référentiel : les autorisations de gestion sont des autorisations pour la branche ou le référentiel. - Modifier la branche par défaut : les politiques d'édition sont des autorisations pour le référentiel. - Importez un référentiel : membre du groupe de sécurité Administrateurs de projet ou détenteur de l’autorisation Créer un référentiel au niveau du projet Git avec la permission Autoriser. Pour plus d'informations, voir Définir les autorisations de référentiel Git. |
| Services | Dépôts activés. |
| Outils | Optional. Utilisez az repos : Azure DevOps CLI. |
Note
Dans les projets publics, les utilisateurs disposant d’un accès aux parties prenantes ont un accès complet à Azure Repos, notamment l’affichage, le clonage et la contribution au code.
| Catégorie | Spécifications |
|---|---|
| Accès au projet | Membre d’un projet. |
| Permissions | - Afficher le code : au moins un accès de base. - Cloner ou contribuer au code : membre du groupe de sécurité Contributeurs ou autorisations correspondantes dans le projet. |
| Services | Dépôts activés. |
Créer une introduction
Commencez votre fichier README avec une brève explication qui décrit votre projet. Ajoutez une capture d’écran ou un GIF animé dans votre introduction si votre projet a une interface utilisateur. Si votre code s’appuie sur une autre application ou bibliothèque, veillez à indiquer ces dépendances dans l’introduction ou en dessous. Les applications et les outils qui s’exécutent uniquement sur des plateformes spécifiques doivent avoir les versions de système d’exploitation prises en charge indiquées dans cette section du fichier README.
Aider vos utilisateurs à démarrer
Dans la section suivante de votre fichier README, guidez les utilisateurs tout au long de l’exécution de votre code sur leur propre système. Restez concentré sur les étapes essentielles pour commencer à utiliser votre code. Lien vers les versions requises de tout logiciel requis afin que les utilisateurs puissent y accéder facilement. Si vous avez des étapes de configuration complexes, documentez ces étapes en dehors de votre fichier README et liez-les.
Indiquez aux lecteurs où obtenir la dernière version. Fournissez l’un des éléments suivants :
- Lien vers un programme d’installation binaire ou un package prédéfini.
- Instructions d’installation à l’aide d’un gestionnaire de package (par exemple, npm install, pip install ou dotnet add package).
Si votre projet est une bibliothèque ou un wrapper d’API, incluez un extrait de code minimal qui montre l’utilisation de base, suivi de la sortie attendue. Ces informations aident les lecteurs à vérifier leur configuration et à comprendre ce que fait la bibliothèque en un clin d’œil.
Fournir des étapes de compilation pour les développeurs
Utilisez la section suivante de votre fichier README pour montrer aux développeurs comment générer votre code à partir d’un nouveau clone du référentiel et exécuter les tests inclus. Effectuez les étapes suivantes :
- Donnez des détails sur les outils nécessaires pour générer le code et documenter les étapes à suivre pour les configurer pour obtenir une build propre.
- Séparez les instructions de compilation denses ou complexes dans une page distincte de votre documentation et liez-la à celle-ci si nécessaire.
- Exécutez les instructions à mesure que vous les écrivez pour vérifier que les instructions fonctionnent pour un nouveau contributeur.
N’oubliez pas que vous êtes peut-être le développeur qui s’appuie sur ces instructions après ne pas travailler sur un projet pendant un certain temps.
Incluez les commandes pour exécuter tous les cas de test fournis avec le code source une fois la build réussie. Les développeurs s’appuient sur ces cas de test pour s’assurer qu’ils ne interrompent pas votre code au fur et à mesure qu’ils apportent des modifications. De bons cas de test servent également d’exemples que les développeurs peuvent utiliser pour générer leurs propres cas de test lorsqu’ils ajoutent de nouvelles fonctionnalités.
Aider les utilisateurs à contribuer
La dernière section de votre fichier README aide les utilisateurs et les développeurs à participer à la création de rapports de problèmes et à suggérer des idées pour améliorer votre code. Les utilisateurs doivent être liés aux canaux où ils peuvent ouvrir des bogues, demander des fonctionnalités ou obtenir de l’aide à l’aide de votre code.
Les développeurs doivent savoir quelles règles ils doivent suivre pour apporter des modifications, telles que les instructions de codage/test et les exigences relatives aux demandes de tirage. Si vous avez besoin d’un accord de contributeur pour accepter des requêtes de fusion ou appliquer un code de conduite communautaire, ce processus doit être lié ou documenté dans cette section. Indiquez la licence sous laquelle le code est publié et liez le texte intégral de la licence.