Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022
Uw Git-opslagplaats moet een README-bestand hebben, zodat kijkers weten wat uw code doet en hoe ze aan de slag kunnen gaan. Uw README-bestand moet de volgende doelgroepen spreken:
- Gebruikers die uw code willen uitvoeren.
- Ontwikkelaars die uw code willen bouwen en testen. Ontwikkelaars zijn ook gebruikers.
- Inzenders die wijzigingen in uw code willen indienen. Inzenders zijn zowel ontwikkelaars als gebruikers.
Schrijf uw README-bestand in Markdown in plaats van tekst zonder opmaak. Met Markdown kunt u eenvoudig tekst opmaken, afbeeldingen opnemen en een koppeling maken naar meer documentatie uit uw README-bestand.
Hier volgen enkele README-bestanden die deze indeling gebruiken en alle drie de doelgroepen spreken. Gebruik ze voor referentie en inspiratie:
Benodigdheden
| Categorie | Vereisten |
|---|---|
| Toegang tot het project | Lid van een project. |
| toestemmingen | - Code weergeven in privéprojecten: minimaal Basis toegang. - Klonen of bijdragen aan code in privéprojecten: lid zijn van de beveiligingsgroep Inzenders of beschikken over de bijbehorende machtigingen in het project. - Machtigingen voor vertakking of opslagplaats instellen: Machtigingen beheren zijn machtigingen voor de vertakking of opslagplaats. - Standaardvertakking wijzigen: Beleidsregels bewerken zijn machtigingen voor de opslagplaats. - Een opslagplaats importeren: Lid van de Projectbeheerders beveiligingsgroep of Git-projectniveau Opslagplaats maken machtiging ingesteld op Toestaan. Zie Machtigingen voor Git-opslagplaatsen instellen voor meer informatie. |
| Services | Repositories ingeschakeld. |
| Gereedschappen | Facultatief. Gebruik az repos opdrachten: Azure DevOps CLI. |
Notitie
In openbare projecten hebben gebruikers met Stakeholder volledige toegang tot Azure Repos, waaronder het weergeven, klonen en bijdragen aan code.
| Categorie | Vereisten |
|---|---|
| Toegang tot het project | Lid van een project. |
| toestemmingen | - Code weergeven: ten minste Basis toegang. - Klonen of bijdragen aan code: Lid van de beveiligingsgroep Contributors of bijbehorende machtigingen in het project. |
| Services | Repositories ingeschakeld. |
Een inleiding maken
Begin uw README-bestand met een korte uitleg over uw project. Voeg een schermafbeelding of GIF-animatie toe in uw inleiding als uw project een gebruikersinterface heeft. Als uw code afhankelijk is van een andere toepassing of bibliotheek, moet u deze afhankelijkheden vermelden in de inleiding of direct eronder. Apps en hulpprogramma's die alleen op specifieke platforms worden uitgevoerd, moeten beschikken over de ondersteunde besturingssysteemversies die in deze sectie van het README-bestand worden vermeld.
Uw gebruikers helpen aan de slag te gaan
In de volgende sectie van uw README-bestand leidt u gebruikers door uw code op hun eigen systeem te laten werken. Blijf gefocust op de essentiële stappen om aan de slag te gaan met uw code. Maak een koppeling naar de vereiste versies van alle vereiste software, zodat gebruikers ze gemakkelijk kunnen bereiken. Als u complexe installatiestappen hebt, documenteer dan deze stappen buiten het README-bestand en koppel deze aan deze stappen.
Vertel lezers waar ze de nieuwste versie kunnen ophalen. Geef een van de volgende items op:
- Een koppeling naar een binair installatieprogramma of vooraf samengesteld pakket.
- Installatie-instructies met behulp van een pakketbeheerder (bijvoorbeeld npm-installatie, pip-installatie of dotnet-pakket toevoegen).
Als uw project een bibliotheek of api-wrapper is, neemt u een minimaal codefragment op dat basisgebruik weergeeft, gevolgd door de verwachte uitvoer. Met deze informatie kunnen lezers hun instellingen controleren en begrijpen wat de bibliotheek in één oogopslag doet.
Bouwstappen bieden voor ontwikkelaars
Gebruik de volgende sectie van uw README-bestand om ontwikkelaars te laten zien hoe ze uw code bouwen vanuit een nieuwe kloon van de opslagplaats en eventuele opgenomen tests uitvoeren. Voer de volgende stappen uit:
- Geef meer informatie over de hulpprogramma's die nodig zijn om de code te bouwen en de stappen te documenteren om ze te configureren om een schone build te krijgen.
- Splits dichte of complexe bouwinstructies op in een afzonderlijke pagina in uw documentatie en koppel deze indien nodig.
- Voer de instructies uit terwijl u ze schrijft om te controleren of de instructies voor een nieuwe inzender werken.
Denk eraan dat u de ontwikkelaar bent die afhankelijk is van deze instructies nadat u enige tijd niet aan een project hebt gewerkt.
Neem de opdrachten op om testcases uit te voeren die bij de broncode worden geleverd nadat de build is geslaagd. Ontwikkelaars leunen op deze testcases om ervoor te zorgen dat ze uw code niet breken wanneer ze wijzigingen aanbrengen. Goede testcases dienen ook als voorbeelden die ontwikkelaars kunnen gebruiken om hun eigen testcases te bouwen wanneer ze nieuwe functionaliteit toevoegen.
Gebruikers helpen bij te dragen
De laatste sectie van uw README-bestand helpt gebruikers en ontwikkelaars om betrokken te raken bij het melden van problemen en het voorstellen van ideeën om uw code beter te maken. Gebruikers moeten verbonden zijn met kanalen waar ze bugs kunnen melden, functies kunnen aanvragen of hulp kunnen krijgen voor het gebruik van uw code.
Ontwikkelaars moeten weten welke regels ze moeten volgen om wijzigingen bij te dragen, zoals richtlijnen voor coderen/testen en vereisten voor pull-aanvragen. Als u een inzenderovereenkomst nodig hebt om pull-aanvragen te accepteren of een communitycode af te dwingen, moet dit proces worden gekoppeld aan of gedocumenteerd in deze sectie. Geef aan onder welke licentie de code wordt vrijgegeven en maak een koppeling naar de volledige tekst van de licentie.