Skapa en README för lagringsplatsen

  • Artikel

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Git-lagringsplatsen bör ha en readme-fil så att användarna vet vad din kod gör och hur de kan komma igång med den. Din readme bör tala med följande målgrupper:

  • Användare som bara vill köra koden.
  • Utvecklare som vill skapa och testa din kod. Utvecklare är också användare.
  • Deltagare som vill skicka ändringar i koden. Deltagare är både utvecklare och användare.

Skriv din readme i Markdown i stället för oformaterad text. Markdown gör det enkelt att formatera text, inkludera bilder och länka efter behov till mer dokumentation från din readme.

Här är några bra readmes som använder det här formatet och talar till alla tre målgrupper, för referens och inspiration:

Skapa ett introduktionstro

Starta läsningen med en kort förklaring som beskriver projektet. Lägg till en skärmbild eller animerad GIF i introduktionen om projektet har ett användargränssnitt. Om koden förlitar sig på ett annat program eller bibliotek ska du ange dessa beroenden i introduktionen eller direkt under den. Appar och verktyg som endast körs på specifika plattformar bör ha de operativsystemversioner som stöds angivna i det här avsnittet av readme.

Hjälp användarna att komma igång

Vägleder användarna genom att få igång koden på sitt eget system i nästa avsnitt av readme. Håll dig fokuserad på de viktigaste stegen för att komma igång med din kod. Länka till nödvändiga versioner av nödvändig programvara så att användarna enkelt kan komma åt dem. Om du har komplexa konfigurationssteg dokumenterar du dem utanför readme och länkar till dem.

Peka på var du kan hämta den senaste versionen av koden. Ett binärt installationsprogram eller instruktioner om hur du använder din kod via paketeringsverktyg är bäst. Om ditt projekt är ett bibliotek eller ett gränssnitt till ett API placerar du ett kodfragment som visar grundläggande användning och visar exempelutdata för koden i kodfragmentet.

Ange byggsteg för utvecklare

Använd nästa avsnitt i readme för att visa utvecklare hur de skapar din kod från en ny klon av lagringsplatsen och kör eventuella tester som ingår. Gör följande:

  • Ge information om de verktyg som behövs för att skapa koden och dokumentera stegen för att konfigurera dem för att få en ren version.
  • Dela upp kompakta eller komplexa bygginstruktioner i en separat sida i dokumentationen och länka till den om det behövs.
  • Kör igenom anvisningarna när du skriver dem för att kontrollera att instruktionerna fungerar för en ny deltagare.

Kom ihåg att utvecklaren som förlitar sig på dessa instruktioner kan vara du när du inte har arbetat med ett projekt under en tid.

Ange kommandona för att köra eventuella testfall som tillhandahålls med källkoden när bygget har slutförts. Utvecklare lutar sig mot dessa testfall för att säkerställa att de inte bryter koden när de gör ändringar. Bra testfall fungerar också som exempel som utvecklare kan använda för att skapa egna testfall när de lägger till nya funktioner.

Hjälp användarna att bidra

Det sista avsnittet i readme hjälper användare och utvecklare att engagera sig i rapporteringsproblem och föreslå idéer för att göra din kod bättre. Användare bör länkas till kanaler där de kan öppna buggar, begära funktioner eller få hjälp med din kod.

Utvecklare behöver veta vilka regler de behöver följa för att bidra med ändringar, till exempel kodnings-/testningsriktlinjer och krav för pull-begäranden. Om du kräver ett deltagaravtal för att acceptera pull-begäranden eller framtvinga en uppförandekod för communityn bör den här processen länkas till eller dokumenteras i det här avsnittet. Ange vilken licens koden släpps under och länka till den fullständiga texten i licensen.