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 | Azure DevOps Server 2022
Il repository Git deve avere un file README in modo che i visualizzatori sappiano cosa fa il codice e come possono iniziare a usarlo. Il file README deve parlare con i destinatari seguenti:
- Utenti che vogliono 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 README in Markdown anziché in testo normale. Markdown semplifica la formattazione del testo, l'inclusione di immagini e il collegamento ad altre documentazione del file README.
Ecco alcuni file README che usano questo formato e parlano a tutti e tre i destinatari. Usarli per riferimento e 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 le autorizzazioni corrispondenti nel progetto. - Impostare le autorizzazioni del ramo o del repository: le autorizzazioni di gestione sono autorizzazioni per il ramo o il repository. - Modifica ramo predefinito: i criteri di modifica sono 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. |
| Tools | Opzionale. Usare i comandi az repos: CLI 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
Iniziare il file README 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 direttamente sotto di essa. Le app e gli strumenti eseguiti solo su piattaforme specifiche devono avere le versioni supportate del sistema operativo indicate in questa sezione del file README.
Aiutare gli utenti a iniziare
Nella sezione successiva del file README, guidare gli utenti nel recupero e nell'esecuzione del codice nel proprio sistema. 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 installazione complessi, documentare questi passaggi all'esterno del file README e collegarli.
Indicare ai lettori dove ottenere la versione più recente. Specificare uno degli elementi seguenti:
- Collegamento a un programma di installazione binario o a un pacchetto predefinito.
- Istruzioni di installazione usando una gestione pacchetti (ad esempio, npm install, pip install o dotnet add package).
Se il progetto è una libreria o un wrapper API, includere un frammento di codice minimo che mostra l'utilizzo di base, seguito dall'output previsto. Queste informazioni consentono ai lettori di verificare la configurazione e comprendere a colpo d'occhio le operazioni della libreria.
Fornire i passaggi di compilazione per gli sviluppatori
Usare la sezione successiva del file README per mostrare agli sviluppatori come compilare il codice da un nuovo clone del repository ed eseguire eventuali test inclusi. Effettua i passaggi 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.
- Eseguire le istruzioni durante la scrittura per verificare che le istruzioni funzionino per un nuovo collaboratore.
Tenere presente che si potrebbe essere lo sviluppatore che si basa su queste istruzioni dopo che non si lavora su un progetto per un certo periodo di tempo.
Includere i comandi per eseguire tutti i test case forniti con il codice sorgente al termine della compilazione. 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 aggiungono nuove funzionalità.
Aiutare gli utenti a contribuire
L'ultima sezione del file README consente agli utenti e agli sviluppatori di partecipare alla segnalazione dei problemi e suggerisce 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.