Creare un file README per il repository

  • Articolo

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Il repository Git deve avere un file leggimi in modo che i visualizzatori sappiano cosa fa il codice e come possono iniziare a usarlo. Il file leggimi dovrebbe parlare con i destinatari seguenti:

  • Utenti che vogliono solo eseguire il codice.
  • Sviluppatori che vogliono compilare e testare il codice. Gli sviluppatori sono anche utenti.
  • Collaboratori che vogliono inviare modifiche al codice. I collaboratori sono sia sviluppatori che utenti.

Scrivere il file leggimi in Markdown invece di testo normale. Markdown semplifica la formattazione del testo, l'inclusione di immagini e il collegamento in base alle esigenze per una maggiore documentazione dal file leggimi.

Ecco alcuni grandi leggimi che usano questo formato e parlano a tutti e tre i destinatari, per riferimento e ispirazione:

Creare un'introduzione

Iniziare il file leggimi con una breve spiegazione che descrive il progetto. Aggiungere uno screenshot o una GIF animata nell'introduzione se il progetto ha un'interfaccia utente. Se il codice si basa su un'altra applicazione o libreria, assicurarsi di dichiarare tali dipendenze nell'introduzione o subito sotto di esso. Le app e gli strumenti eseguiti solo su piattaforme specifiche devono avere le versioni supportate del sistema operativo annotate in questa sezione del file leggimi.

Aiutare gli utenti a iniziare

Guida gli utenti a ottenere il codice in esecuzione nel proprio sistema nella sezione successiva del file leggimi. Rimanere concentrati sui passaggi essenziali per iniziare a usare il codice. Collegarsi alle versioni necessarie di qualsiasi software prerequisito in modo che gli utenti possano raggiungerli facilmente. Se sono presenti passaggi di configurazione complessi, documentarli all'esterno del file leggimi e collegarli.

Indica dove ottenere la versione più recente del codice. Un programma di installazione binario o istruzioni sull'uso del codice tramite gli strumenti di creazione di pacchetti è ottimale. Se il progetto è una libreria o un'interfaccia per un'API, inserire un frammento di codice che mostra l'utilizzo di base e mostrare l'output di esempio per il codice in tale frammento.

Fornire i passaggi di compilazione per gli sviluppatori

Usare la sezione successiva del file leggimi per mostrare agli sviluppatori come compilare il codice da un nuovo clone del repository ed eseguire eventuali test inclusi. Effettua le operazioni seguenti:

  • Fornire informazioni dettagliate sugli strumenti necessari per compilare il codice e documentare i passaggi per configurarli per ottenere una compilazione pulita.
  • Suddividere le istruzioni di compilazione dense o complesse in una pagina separata nella documentazione e collegarla, se necessario.
  • Eseguire le istruzioni durante la scrittura per verificare che le istruzioni funzionino per un nuovo collaboratore.

Tenere presente che lo sviluppatore che si basa su queste istruzioni potrebbe essere l'utente dopo che non si lavora su un progetto per un certo periodo di tempo.

Specificare i comandi per eseguire tutti i test case forniti con il codice sorgente dopo che la compilazione ha avuto esito positivo. Gli sviluppatori si affidano a questi test case per assicurarsi che non interrompano il codice man mano che apportano modifiche. I test case validi fungono anche da esempi che gli sviluppatori possono usare per creare test case personalizzati quando si aggiungono nuove funzionalità.

Aiutare gli utenti a contribuire

L'ultima sezione del file leggimi aiuta gli utenti e gli sviluppatori a partecipare alla segnalazione dei problemi e suggerire idee per migliorare il codice. Gli utenti devono essere collegati ai canali in cui possono aprire bug, richiedere funzionalità o ottenere assistenza usando il codice.

Gli sviluppatori devono sapere quali regole devono seguire per contribuire alle modifiche, ad esempio le linee guida di codifica/test e i requisiti delle richieste pull. Se è necessario un contratto di collaboratore per accettare richieste pull o applicare un codice di comportamento della community, questo processo deve essere collegato o documentato in questa sezione. Specificare la licenza in cui viene rilasciato il codice e collegarsi al testo completo della licenza.