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 leesmij-bestand hebben, zodat kijkers weten wat uw code doet en hoe ze aan de slag kunnen gaan. Uw readme-bestand moet zich richten tot de volgende doelgroepen:
- Gebruikers die alleen 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 leesmij in Markdown- in plaats van tekst zonder opmaak. Markdown maakt het eenvoudig om tekst op te maken, afbeeldingen op te nemen en indien nodig te koppelen aan aanvullende documentatie van uw readme-bestand.
Hier volgen enkele geweldige leesbewerkingen die deze indeling gebruiken en alle drie de doelgroepen spreken, ter 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 van de Inzenders beveiligingsgroep of bijbehorende machtigingen in het project. - Machtigingen instellen voor vertakking of opslagplaats: Beheer machtigingen voor de vertakking of opslagplaats. - Standaardtak wijzigen: beleid bewerken 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. |
| Diensten | 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. |
| Diensten | Repositories ingeschakeld. |
Een inleiding maken
Begin uw README met een korte uitleg over uw project. Voeg een schermafbeelding of GIF-animatie toe aan 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 de ondersteunde besturingssysteemversies hebben die in deze sectie van het leesmij-bestand worden vermeld.
Uw gebruikers helpen aan de slag te gaan
Leid gebruikers in het volgende gedeelte van je readme door het proces om je 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 deze dan buiten uw readme-bestand en verwijs daarnaar.
Geef aan waar u de nieuwste versie van uw code kunt downloaden. Een binair installatieprogramma of instructies voor het gebruik van uw code via verpakkingshulpprogramma's is het beste. Als uw project een bibliotheek of een interface naar een API is, plaatst u een codefragment met basisgebruik en geeft u voorbeelduitvoer weer voor de code in dat fragment.
Bouwstappen bieden voor ontwikkelaars
Gebruik de volgende sectie van je handleiding om ontwikkelaars te laten zien hoe ze je code opbouwen vanuit een nieuwe kloon van de repository en eventuele inbegrepen tests uitvoeren. Ga als volgt te werk:
- 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 werken voor een nieuwe inzender.
Houd er rekening mee dat jij de ontwikkelaar kunt zijn die op deze instructies vertrouwt na een tijdje niet aan een project te hebben gewerkt.
Geef 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 bij het toevoegen van nieuwe functionaliteit.
Gebruikers helpen bij te dragen
Met de laatste sectie van uw leesmij kunnen gebruikers en ontwikkelaars betrokken raken bij het melden van problemen en ideeën voorstellen 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.