Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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 rivolgersi ai seguenti destinatari:
- 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.
Scrivi il tuo file leggimi in Markdown anziché in testo semplice. Markdown semplifica la formattazione del testo, l'inclusione di immagini e creare collegamenti alla documentazione aggiuntiva necessaria dalla tua readme.
Ecco alcune ottime documentazioni che usano questo formato e sono rivolte a tutte e tre le tipologie di destinatari, come riferimento e fonte di ispirazione.
Prerequisiti
| Categoria | Requisiti |
|---|---|
| Accesso al progetto | Membro di un progetto. |
| Autorizzazioni | - Visualizzare il codice nei progetti privati: almeno livello di accesso Basic . - Clonare o contribuire al codice nei progetti privati: membro del gruppo di sicurezza Contributors o con autorizzazioni corrispondenti nel progetto. - Impostare le autorizzazioni per il ramo o il repository: Gestisci le autorizzazioni per il ramo o il repository. - Modificare il ramo predefinito: Modificare le politiche le autorizzazioni per il repository. - Importare un repository: membro del gruppo di sicurezza amministratori del progetto o autorizzazione a livello di progetto Git Crea repository impostata su Consenti. Per altre informazioni, vedere Impostare le autorizzazioni del repository Git. |
| Servizi | Repos abilitato. |
| Strumenti | Opzionale. Usare i comandi az repos: l'interfaccia della riga di comando di Azure DevOps. |
Nota
Nei progetti pubblici, gli utenti con accesso Stakeholder hanno pieno accesso ad Azure Repos, compresa la visualizzazione, la clonazione e il contribuire al codice.
| Categoria | Requisiti |
|---|---|
| Accesso al progetto | Membro di un progetto. |
| Autorizzazioni | - Visualizzare il codice: almeno accesso di base. - Clonare o contribuire al codice: membro del gruppo di sicurezza Contributor o autorizzazioni corrispondenti nel progetto. |
| Servizi | Repos abilitato. |
Creare un'introduzione
Inizia il file leggimi con una breve spiegazione che descrive il tuo 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 eseguire il codice sul proprio sistema nella sezione successiva del tuo README. 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.
- Suddividi le istruzioni di compilazione dense o complesse in una pagina separata nella documentazione e collegati ad essa se necessario.
- Verifica le istruzioni mentre le redigi per assicurarti che siano efficaci per un nuovo collaboratore.
Ricorda, lo sviluppatore che si basa su queste istruzioni potresti essere tu stesso dopo aver smesso di lavorare su un progetto per un po' 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.