Scrivi un README o un changelog in pochi minuti

Compila un breve modulo e ottieni un README.md ordinato con passaggi di installazione, utilizzo, configurazione e licenza, oppure un CHANGELOG.md nel formato Keep a Changelog. Guarda il risultato mentre scrivi. Tutto viene scritto nel tuo browser, e niente di ciò che scrivi viene caricato. È gratis.

Come creare un README, passo dopo passo

1. Scegli README.md in alto.
2. Sotto Informazioni sul progetto, inserisci il Nome del progetto, un Riassunto in una riga, una Descrizione, e le Funzionalità e i Requisiti, uno per riga.
3. Sotto Installa e usa, scegli un Gestore di pacchetti come npm, pip o Cargo, aggiungi l'URL del repository e scrivi il tuo Utilizzo. Scegli il linguaggio dell'Utilizzo così il codice viene formattato correttamente.
4. Aggiungi i comandi di Impostazioni e Sviluppo se si applicano.
5. Scegli una Licenza e un Titolare del copyright, e attiva l'Indice, il badge della Licenza o la sezione Contribuire secondo necessità.
6. Premi Copia Markdown o Scarica README.md.

Cosa rende buono un README

Di' cosa fa il progetto in una riga, poi mostra come installarlo e il più piccolo esempio che funziona. I lettori decidono in pochi secondi se un progetto fa al caso loro, quindi funzionalità e requisiti vengono dopo, seguiti da impostazioni, comandi di sviluppo, come contribuire e la licenza. Le sezioni che lasci vuote vengono escluse.

Changelog che le persone sanno leggere

Il changelog segue Keep a Changelog: prima il rilascio più recente, ciascuno con una data e le sue modifiche raggruppate come Aggiunto, Modificato, Deprecato, Rimosso, Corretto e Sicurezza. Tieni una sezione Unreleased in cima per le modifiche non ancora rilasciate. Con l'indirizzo di un repository, ogni versione rimanda al confronto con la precedente. Puoi aggiungere un rilascio più vecchio a mano, oppure creare voci dai messaggi di commit.

Consigli

• Metti un comando di installazione funzionante e un breve esempio di utilizzo in alto.
• Indica chiaramente la licenza così gli altri sanno come possono usare il tuo codice.
• Tieni la descrizione su ciò che il progetto fa per il lettore, non su come lo hai costruito.
• Aggiorna il changelog a ogni rilascio, non solo alla fine.

Per tenere segreti e file di build fuori da un repository, usa il generatore di .gitignore e il generatore di env example.

Domande

Posso partire dalla cronologia dei commit?

Sì. Incolla l'output di git log --oneline sotto From commit messages. I commit scritti come feat:, fix:, perf: e così via vengono ordinati nei gruppi giusti, e le modifiche incompatibili segnate con un punto esclamativo vengono etichettate. Modifica poi le formulazioni; i messaggi di commit sono scritti per gli sviluppatori, i changelog per gli utenti.

Aggiunge il testo della licenza?

Aggiunge una sezione License che indica la licenza e rimanda a un file LICENSE. Metti il testo completo della licenza in quel file; la pagina ufficiale della licenza ce l'ha.

Dove vanno i file?

Download salva README.md o CHANGELOG.md sul tuo dispositivo. Mettilo al livello principale del tuo repository e i servizi di hosting del codice lo mostreranno nella pagina del progetto.

Quali licenze posso scegliere?

MIT, Apache 2.0, GPL 3.0, BSD 3-Clause, ISC, MPL 2.0, Unlicense o All rights reserved, oppure lascia fuori la sezione.