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 lisez-moi afin que les visionneuses sachent ce que fait votre code et comment ils peuvent commencer à l’utiliser. Votre lisez-moi doit parler aux audiences suivantes :
- Utilisateurs qui souhaitent simplement 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 lisez-moi dans Markdown au lieu de texte brut. Markdown permet de mettre en forme facilement du texte, d’inclure des images et de lier en fonction des besoins pour plus de documentation à partir de votre fichier lisez-moi.
Voici quelques excellents lisez-moi qui utilisent ce format et parlent aux trois audiences, pour référence et inspiration :
Prerequisites
| Catégorie | Spécifications |
|---|---|
| Accès au projet | Membre d’un projet. |
| Permissions | - Afficher le code dans des projets privés : accès au moins de base . - Clonez ou contribuez au code dans des projets privés : membre du groupe de sécurité Contributeurs ou autorisations correspondantes dans le projet. - Définir des autorisations de branche ou de référentiel : gérer les autorisations pour la branche ou le référentiel. - Modifier la branche par défaut : modifiez les autorisations des stratégies pour le référentiel. - Importez un référentiel : membre du groupe de sécurité Administrateurs de projet ou de l’autorisation Créer au niveau du projet Git surAutoriser. Pour plus d'informations, voir Définir les autorisations de référentiel Git. |
| Services | Dépôts activés. |
| Outils | Optional. Utilisez les commandes 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 : Accès de base au moins. - 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
Démarrez votre fichier lisez-moi avec une brève explication décrivant votre projet. Ajoutez une capture d’écran ou une image GIF animée 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 juste 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 lisez-moi.
Aider vos utilisateurs à démarrer
Guidez les utilisateurs dans l’obtention de votre code en cours d’exécution sur leur propre système dans la section suivante de votre fichier lisez-moi. Restez concentré sur les étapes essentielles pour commencer à utiliser votre code. Lier les versions requises de n’importe quel logiciel requis afin que les utilisateurs puissent y accéder facilement. Si vous avez des étapes de configuration complexes, documentez-les en dehors de votre fichier lisez-moi et liez-les.
Indiquez où obtenir la dernière version de votre code. Un programme d’installation binaire ou des instructions sur l’utilisation de votre code par le biais d’outils d’empaquetage est préférable. Si votre projet est une bibliothèque ou une interface vers une API, placez un extrait de code montrant l’utilisation de base et affichez l’exemple de sortie du code dans cet extrait de code.
Fournir des étapes de génération pour les développeurs
Utilisez la section suivante de votre fichier lisez-moi 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 actions 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.
- Découvrez des instructions de build denses ou complexes dans une page distincte de votre documentation et liez-la 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 le développeur qui s’appuie sur ces instructions peut être vous après ne pas travailler sur un projet pendant un certain temps.
Fournissez 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 lors de l’ajout de nouvelles fonctionnalités.
Aider les utilisateurs à contribuer
La dernière section de votre fichier lisez-moi 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 demandes de tirage 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.