Crea un README
Suggerimenti per un buon README
Ogni progetto è diverso, quindi considera quale di queste sezioni si applica al tuo. Le sezioni utilizzate nel modello sono suggerimenti per la maggior parte dei progetti open source. Inoltre, tieni presente che mentre un README può essere troppo lungo e dettagliato, troppo lungo è meglio che troppo breve. Se pensi che il tuo README sia troppo lungo, considera di utilizzare un’altra forma di documentazione piuttosto che tagliare le informazioni.
Nome
Scegli un nome auto-esplicativo per il tuo progetto.,
Descrizione
Fai sapere alle persone cosa può fare il tuo progetto in modo specifico. Fornire contesto e aggiungere un link a qualsiasi visitatore di riferimento potrebbe non avere familiarità con. Un elenco di caratteristiche o una sottosezione di sfondo può anche essere aggiunto qui. Se ci sono alternative al tuo progetto, questo è un buon posto per elencare i fattori di differenziazione.
Badge
Su alcuni READMEs, potresti vedere piccole immagini che trasmettono metadati, ad esempio se tutti i test stanno passando o meno per il progetto. È possibile utilizzare Scudi per aggiungere alcuni al README. Molti servizi hanno anche istruzioni per l’aggiunta di un badge.,
Visuals
A seconda di ciò che si sta facendo, può essere una buona idea per includere screenshot o anche un video (vedrete spesso GIF piuttosto che video reali). Strumenti come ttygif possono aiutare, ma controlla Asciinema per un metodo più sofisticato.
Installazione
All’interno di un particolare ecosistema, ci può essere un modo comune di installare le cose, come l’utilizzo di filato, NuGet, o Homebrew. Tuttavia, considera la possibilità che chiunque stia leggendo il tuo README sia un novizio e desideri maggiori indicazioni., L’elenco di passaggi specifici aiuta a rimuovere l’ambiguità e consente alle persone di utilizzare il progetto il più rapidamente possibile. Se viene eseguito solo in un contesto specifico come una particolare versione del linguaggio di programmazione o un sistema operativo o ha dipendenze che devono essere installate manualmente, aggiungere anche una sottosezione Requisiti.
Usage
Usa gli esempi liberamente e mostra l’output previsto se puoi. E ” utile avere in linea il più piccolo esempio di utilizzo che si può dimostrare, fornendo collegamenti a esempi più sofisticati se sono troppo lunghi per includere ragionevolmente nel README.,
Supporto
Dire alle persone dove possono andare per chiedere aiuto. Può essere qualsiasi combinazione di un tracker di problemi, una chat room, un indirizzo email, ecc.
Roadmap
Se hai idee per le versioni future, è una buona idea elencarle nel README.
Contributing
Dichiara se sei aperto ai contributi e quali sono i tuoi requisiti per accettarli.
Per le persone che vogliono apportare modifiche al progetto, è utile avere qualche documentazione su come iniziare., Forse c’è uno script che dovrebbero eseguire o alcune variabili di ambiente che devono impostare. Rendere questi passaggi espliciti. Queste istruzioni potrebbero anche essere utili per il vostro sé futuro.
È anche possibile documentare i comandi per lint il codice o eseguire test. Questi passaggi aiutano a garantire un’elevata qualità del codice e riducono la probabilità che le modifiche interrompano inavvertitamente qualcosa. Avere istruzioni per l’esecuzione dei test è particolarmente utile se richiede una configurazione esterna, ad esempio l’avvio di un server Selenium per il test in un browser.,
Autori e riconoscimenti
Mostra il tuo apprezzamento a coloro che hanno contribuito al progetto.
Licenza
Per i progetti open source, dire come è concesso in licenza.
Stato del progetto
Se hai esaurito l’energia o il tempo per il tuo progetto, metti una nota in cima al README dicendo che lo sviluppo è rallentato o fermato completamente. Qualcuno può scegliere di biforcare il tuo progetto o fare volontariato per intervenire come manutentore o proprietario, consentendo al tuo progetto di andare avanti. Puoi anche fare una richiesta esplicita per i manutentori.