Lav en README
forslag til en god README
hvert projekt er anderledes, så overvej hvilke af disse sektioner der gælder for din. De afsnit, der bruges i skabelonen, er forslag til de fleste open source-projekter. Husk også, at mens en README kan være for lang og detaljeret, er for lang bedre end for kort. Hvis du synes, at din README er for lang, skal du overveje at bruge en anden form for dokumentation snarere end at skære ud information.
navn
Vælg et selvforklarende navn til dit projekt.,
beskrivelse
Lad folk vide, hvad dit projekt kan gøre specifikt. Giv kontekst og tilføj et link til enhver reference besøgende kan være bekendt med. En liste over funktioner eller et underafsnit i baggrunden kan også tilføjes her. Hvis der er alternativer til dit projekt, er dette et godt sted at liste differentierende faktorer.
Badges
på nogle READMEs kan du muligvis se små billeder, der formidler metadata, f.eks. Du kan bruge skjolde til at tilføje nogle til din README. Mange tjenester har også instruktioner til at tilføje et badge.,
Visuals
afhængigt af hvad du laver, kan det være en god ide at inkludere skærmbilleder eller endda en video (du”vil ofte se GIF’ er snarere end faktiske videoer). Værktøjer som ttygif kan hjælpe, men tjek Asciinema for en mere sofistikeret metode.
Installation
inden for et bestemt økosystem kan der være en almindelig måde at installere ting på, såsom at bruge Garn, NuGet eller Homebre.. Overvej dog muligheden for, at den, der læser din README, er en nybegynder og gerne vil have mere vejledning., Notering specifikke trin hjælper med at fjerne tvetydighed og får folk til at bruge dit projekt så hurtigt som muligt. Hvis det kun kører i en bestemt sammenhæng som en bestemt programmeringssprogversion eller operativsystem eller har afhængigheder, der skal installeres manuelt, skal du også tilføje et underafsnit om krav.
anvendelse
brug eksempler liberalt, og vis det forventede output, hvis du kan. Det ” s nyttigt at have inline den mindste eksempel på brug, som du kan demonstrere, samtidig med at links til mere sofistikerede eksempler, hvis de er for lange til rimeligt at medtage i README.,
Support
Fortæl folk, hvor de kan gå til for at få hjælp. Det kan være enhver kombination af et problem tracker, et chatrum, en e-mail-adresse, etc.
køreplan
Hvis du har ideer til udgivelser i fremtiden, er det en god ide at liste dem i README.
bidragende
Angiv, om du er åben for bidrag, og hvad dine krav er for at acceptere dem.
for folk, der ønsker at foretage ændringer i dit projekt, er det nyttigt at have nogle dokumentation om, hvordan du kommer i gang., Måske er der et script, som de skal køre eller nogle miljøvariabler, som de skal indstille. Gør disse trin eksplicit. Disse instruktioner kan også være nyttige for dit fremtidige selv.
Du kan også dokumentere kommandoer for at lint koden eller køre test. Disse trin hjælper med at sikre høj kodekvalitet og reducere sandsynligheden for, at ændringerne utilsigtet bryder noget. At have instruktioner til at køre test er især nyttigt, hvis det kræver ekstern opsætning, såsom at starte en Selenserver til test i en bro .ser.,
forfattere og anerkendelse
Vis din påskønnelse til dem, der har bidraget til projektet.
Licens
for open source-projekter skal du sige, hvordan det er licenseret.
projektstatus
Hvis du er løbet tør for energi eller tid til dit projekt, skal du sætte en note øverst i README, der siger, at udviklingen er bremset eller stoppet helt. Nogen kan vælge at punge dit projekt eller frivillige til at træde ind som vedligeholder eller ejer, så dit projekt til at holde i gang. Du kan også stille en eksplicit anmodning til vedligeholdere.