Contribuire ai repository di documentazione .NET

Grazie per l'interesse dimostrato nell'apporto di contributi alla documentazione di .NET.

Questo documento illustra il processo per apportare contribuiti agli articoli e agli esempi di codice ospitati nel sito della documentazione .NET. I contributi possono essere semplici come le correzioni di errori di ortografia o complessi, ad esempio nuovi articoli.

Il sito della documentazione .NET è compilato da più repository. Questi sono solo alcuni di essi:

• Articoli concettuali e frammenti di codice per .NET
• Esempi e frammenti di codice
• Informazioni di riferimento sulle API .NET
• Riferimento di .NET Compiler Platform SDK
• Informazioni di riferimento sulle API ML.NET

Linee guida per i contributi

Apprezziamo i contributi della community alla documentazione. L'elenco seguente illustra alcune regole guida da tenere presenti quando si contribuisce alla documentazione di .NET:

• NON inviare richieste pull di grandi dimensioni. Al contrario, segnalare un problema e avviare una discussione in modo che si possa concordare una direzione prima di investire una grande quantità di tempo.
• NON includere codice di esempio inline in un articolo.
• Usare un progetto di frammento di codice con codice da incorporare nell'articolo.
• SEGUIRE queste istruzioni e le linee guida per voce e tono.
• USARE il file modello come punto di partenza del proprio lavoro.
• CREARE un ramo separato nel fork prima di lavorare sugli articoli.
• SEGUIRE il flusso GitHub.
• PUBBLICARE AGGIORNAMENTI tramite blog e tweet (o altri strumenti) sui contributi, se lo si ritiene opportuno.

Seguendo queste linee guida si garantirà un'esperienza migliore per tutti.

Processo di contributo

Passaggio 1: se si è interessati a scrivere nuovo contenuto o a rivedere completamente il contenuto esistente, aprire un problema che descrive le operazioni da eseguire. Il contenuto all'interno della cartella docs è organizzato in sezioni riflesse nel sommario (TOC). Definire la posizione del sommario in cui verrà inserito l'argomento. Ottenere feedback sulla proposta.

oppure

Scegliere un problema esistente e risolverlo. È possibile dare un'occhiata all'elenco dei problemi aperti e offrirsi come volontari per lavorare a quelli di proprio interesse:

• Filtrare in base all'etichetta del primo problema valido per, bene, buoni problemi.
• Filtrare in base all'etichetta della Guida per individuare i problemi appropriati per il contributo della community. Questi problemi in genere richiedono un contesto minimo.
• I collaboratori esperti possono affrontare qualsiasi problema di loro interesse.

Quando si trova un problema su cui lavorare, aggiungere un commento per richiedere se è aperto.

Dopo aver selezionato un'attività da eseguire, creare un account GitHub e passare al passaggio 2.

Passaggio 2: creare un fork del /dotnet/docs repository (o a qualsiasi repository a cui si sta contribuendo) in base alle esigenze e creare un ramo per le modifiche.

Per piccole modifiche, vedere Modifica nel browser.

Passaggio 3: Apportare le modifiche in questo nuovo ramo.

Se si tratta di un nuovo argomento, è possibile usare questo file modello come punto di partenza. Il file contiene le linee guida per la scrittura e illustra anche i metadati necessari per ogni articolo, ad esempio le informazioni sull'autore. Per altre informazioni sulla sintassi Markdown usata nel contenuto di Microsoft Learn, vedere Le informazioni di riferimento su Markdown.

Passare alla cartella corrispondente al percorso del sommario determinato per l'articolo nel passaggio 1. Questa cartella contiene i file markdown per tutti gli articoli nella sezione. Se necessario, creare una nuova cartella in cui inserire i file per il contenuto. L'articolo principale di tale sezione è denominato index.md.

Per le immagini e le altre risorse statiche, creare una sottocartella denominata media all'interno della cartella contenente l'articolo, se non esiste già. Nella cartella media creare una sottocartella con il nome dell'articolo (tranne che per il file di indice). Per altre informazioni sulla posizione dei file, vedere la sezione Struttura di cartelle di esempio.

Non includere codice inline nell'articolo, a meno che non si stia dimostrando un costrutto che non viene compilato. Usare invece un progetto di frammenti di codice e includere il codice usando l'estensione del codice. Ciò garantisce che il codice di esempio venga convalidato dal sistema CI.

Per i frammenti di codice creare una sottocartella denominata snippets all'interno della cartella che contiene l'articolo, se non esiste già. Nella cartella snippets creare una sottocartella con il nome dell'articolo. Nella maggior parte dei casi saranno disponibili frammenti di codice per tutti e tre i principali linguaggi .NET, ovvero C#, F# e Visual Basic. In tal caso, creare sottocartelle denominate csharp, fsharp e vb per ognuno dei tre progetti. Se si crea un frammento di codice per un articolo nelle cartelle docs/csharp, docs/fsharp o docs/visual-basic, il frammento di codice sarà disponibile in un solo linguaggio, quindi è possibile omettere la sottocartella del linguaggio. Per altre informazioni sulla posizione dei file, vedere la sezione Struttura di cartelle di esempio.

I frammenti di codice sono esempi di codice piccoli e mirati che illustrano i concetti trattati in un articolo. I programmi più grandi, destinati al download e all'esplorazione, devono essere posizionati nel repository dotnet/samples. Gli esempi completi sono trattati nella sezione Contributi per gli esempi.

Passaggio 4: Inviare una richiesta pull dal ramo al ramo predefinito.

Ogni richiesta pull deve in genere risolvere un problema alla volta, a meno che più problemi non siano correlati alla stessa correzione della richiesta pull. La richiesta pull può modificare uno o più file. Se è necessario apportare più correzioni in file diversi, è preferibile inviare richieste pull separate.

Se la richiesta pull risolve un problema esistente, aggiungere la Fixes #Issue_Number parola chiave alla descrizione della richiesta pull. In questo modo, il problema viene chiuso automaticamente quando viene eseguito il merge della richiesta pull. Per altre informazioni, vedere Collegamento di una richiesta pull a un problema tramite una parola chiave.

Il team di .NET esaminerà la richiesta pull e informerà l'utente se sono necessari altri aggiornamenti o modifiche per l'approvazione.

Passaggio 5: eseguire gli aggiornamenti necessari per il ramo come discusso con il team.

I gestori uniranno la richiesta pull nel ramo predefinito dopo l'applicazione del feedback e la modifica viene approvata.

Tutti i commit vengono caricati regolarmente dal ramo predefinito nel ramo live e quindi sarà possibile visualizzare il contributo disponibile nella documentazione di .NET. La pubblicazione avviene di solito giornalmente nei giorni lavorativi.

Esempio di struttura di cartelle

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
          portability_report.png
        /shared ...
      /snippets
        /porting-overview
          /csharp
            porting.csproj
            porting-overview.cs
            Program.cs
          /fsharp
            porting.fsproj
            porting-overview.fs
            Program.fs
          /vb
            porting.vbproj
            porting-overview.vb
            Program.vb
        /shared
          /csharp ...
          /fsharp ...
          /vb ...

La struttura illustrata in precedenza include un'immagine, portability_report.png, e tre progetti di codice che includono i frammenti di codice inclusi nell'articolo porting-overview.md.

I frammenti di codice/cartella condivisa vengono usati per frammenti di codice che possono estendersi su più articoli all'interno della stessa cartella padre, ad esempio la cartella di conversione nell'esempio precedente. Usa la cartella condivisa solo quando hai un motivo specifico per farlo, ad esempio il codice XAML a cui fa riferimento più articoli, ma non può ancora essere compilato nella cartella specifica dell'articolo.

I supporti possono anche essere condivisi tra gli articoli quando questi articoli si trovano nella stessa cartella padre, ad esempio la cartella di conversione nell'esempio precedente. Questa cartella condivisa deve essere evitata, se possibile, e usata solo quando ha senso. Ad esempio, può essere opportuno condividere una schermata di caricamento comune per l'app in fase di dimostrazione o condividere finestre di dialogo di Visual Studio riutilizzate in più articoli.

Fornire il proprio contributo per gli esempi

Viene fatta la distinzione seguente per il codice che supporta il contenuto:

• Esempi: i lettori possono scaricare ed eseguire gli esempi. Tutti gli esempi devono essere librerie o applicazioni complete. Se l'esempio crea una libreria, deve includere gli unit test o un'applicazione che consente ai lettori di eseguire il codice. Spesso vengono usati più toolkit, tecnologie o funzionalità. Il file readme.md per ogni esempio farà riferimento all'articolo in modo da poter leggere altre informazioni sui concetti illustrati.
• Frammenti di codice: illustrano un concetto o un'attività più ridotta. Eseguono la compilazione, ma non sono applicazioni complete. Devono poter essere eseguiti correttamente, ma non rappresentano un'applicazione di esempio per uno scenario tipico. Sono invece progettati per illustrare singoli concetti o funzionalità con il minor codice possibile. Non dovrebbero essere composti da più di una schermata di codice.

Gli esempi vengono archiviati nel repository dotnet/samples. Microsoft sta lavorando a un modello in cui la struttura della cartella samples corrisponda alla struttura della cartella docs. Gli standard seguiti sono:

• Le cartelle di primo livello corrispondono alle cartelle di primo livello nel repository docs. Il repository docs include, ad esempio, una cartella machine-learning/tutorials e gli esempi per le esercitazioni su Machine Learning si trovano nella cartella samples/machine-learning/tutorials.

Inoltre, tutti gli esempi nelle cartelle core e standard devono essere compilati ed eseguiti in tutte le piattaforme supportate da .NET Core. Il sistema di compilazione CI imporrà questo requisito. La cartella framework di primo livello contiene esempi che vengono eseguiti e convalidati solo in Windows.

I progetti di esempio devono poter essere compilati ed eseguiti nel set di piattaforme più ampio possibile per l'esempio specifico. In pratica ciò significa creare applicazioni console basate su .NET Core quando possibile. Gli esempi specifici per il Web o per un framework di interfaccia utente devono includere gli strumenti appositi. Sono esempi di questo tipo le applicazioni Web, le app per dispositivi mobili, le app WPF o WinForms e così via.

È in progetto l'implementazione di un sistema CI per tutto il codice. Quando si aggiornano gli esempi, assicurarsi che ogni aggiornamento faccia parte di un progetto compilabile. Idealmente, aggiungere anche test per verificare la correttezza degli esempi.

Ogni esempio completo creato deve contenere un file readme.md. Questo file deve contenere una breve descrizione dell'esempio (uno o due paragrafi). Il file readme.md deve indicare ai lettori quali informazioni otterranno esplorando questo esempio. Il file readme.md deve contenere anche un collegamento al documento live nel sito della documentazione di .NET. Per determinare dove un determinato file del repository esegue il mapping a tale sito, sostituire /docs nel percorso del repository con https://video2.skills-academy.com/dotnet.

L'argomento conterrà anche collegamenti all'esempio. Creare un collegamento diretto alla cartella dell'esempio in GitHub.

Scrivere un nuovo esempio

Gli esempi sono programmi completi e librerie destinati al download. Possono avere un ambito ridotto, ma illustrano i concetti in modo da consentire agli utenti di esplorare e sperimentare autonomamente. Le linee guida per gli esempi assicurano che i lettori possano scaricarli ed esplorarli. Esaminare gli esempi per Parallel LINQ (PLINQ) come esempio di ciascuna delle linee guida.

1. L'esempio deve fare parte di un progetto compilabile. Se possibile, i progetti devono poter essere compilati per tutte le piattaforme supportate da .NET Core. Rappresentano un'eccezione gli esempi dimostrativi di una funzionalità specifica di una piattaforma o di uno strumento specifico di una piattaforma.

2. L'esempio deve essere conforme allo stile di codifica di runtime per mantenere la coerenza.

   È inoltre preferibile usare metodi static anziché metodi di istanza per la dimostrazione di scenari che non richiedono la creazione di una nuova istanza di oggetto.

3. L'esempio deve includere codice appropriato per la gestione delle eccezioni e prevedere la gestione di tutte le eccezioni che è probabile vengano generate nel contesto dell'esempio. Ad esempio, un esempio che chiama il metodo Console.ReadLine per recuperare l'input dell'utente deve usare codice di gestione delle eccezioni appropriato quando la stringa di input viene passata come argomento a un metodo. In modo analogo, se una chiamata di metodo nell'esempio potrebbe avere esito negativo, occorre gestire l'eccezione risultante. Gestire sempre le eccezioni specifiche generate dal metodo, piuttosto che le eccezioni della classe di base, come Exception o SystemException.

Per creare un esempio:

1. Registrare un problema o aggiungere un commento a uno esistente per indicare l'intenzione di lavorarci.

2. Scrivere l'argomento che spiega i concetti dimostrati dall'esempio (ad esempio: docs/standard/linq/where-clause.md).

3. Scrivere l'esempio (ad esempio: WhereClause-Sample1.cs).

4. Creare un file Program.cs con un punto di ingresso Main che chiama gli esempi. Se è già disponibile, aggiungere la chiamata all'esempio:

   public class Program
   {
       public void Main(string[] args)
       {
           WhereClause1.QuerySyntaxExample();
   
           // Add the method syntax as an example.
           WhereClause1.MethodSyntaxExample();
       }
   }
   

È possibile compilare qualsiasi frammento di codice .NET o esempio usando l'interfaccia della riga di comando di .NET, che può essere installato con .NET SDK. Per compilare ed eseguire l'esempio:

1. Passare alla cartella dell'esempio e compilarlo per verificare se sono presenti errori:

   dotnet build
   

2. Eseguire l'esempio:

   dotnet run
   

3. Aggiungere un file readme.md nella directory radice dell'esempio.

   Il file deve includere una breve descrizione del codice e indirizzare gli utenti all'articolo che fa riferimento all'esempio. Nella parte superiore del file readme.md devono essere presenti i metadati necessari per il sito di esplorazione degli esempi. Il blocco di intestazione deve contenere i campi seguenti:

   ---
   name: "really cool sample"
   description: "Learn everything about this really cool sample."
   page_type: sample
   languages:
     - csharp
     - fsharp
     - vbnet
   products:
     - dotnet-core
     - dotnet
     - dotnet-standard
     - aspnet
     - aspnet-core
     - ef-core
   ---
   

   • La raccolta languages deve includere solo i linguaggi disponibili per l'esempio.
   • La raccolta products deve includere solo i prodotti rilevanti per l'esempio.

Tranne dove indicato, tutti gli esempi vengono compilati dalla riga di comando in qualsiasi piattaforma supportata da .NET. Esistono alcuni esempi specifici di Visual Studio che richiedono Visual Studio 2017 o versioni successive. Alcuni esempi, inoltre, illustrano funzionalità specifiche di una piattaforma e richiederanno una piattaforma specifica. Altri esempi e frammenti di codice richiedono .NET Framework e verranno eseguiti su piattaforme Windows e sarà necessario il Developer Pack per la versione di .NET Framework di destinazione.

Esperienza interattiva in C#

Tutti i frammenti di codice inclusi in un articolo usano un tag di lingua per indicare la lingua di origine. I frammenti di codice brevi in C# possono usare il tag del csharp-interactive linguaggio per specificare un frammento di codice C# eseguito nel browser. I frammenti di codice inline usano il csharp-interactive tag , per i frammenti inclusi dall'origine, usare il code-csharp-interactive tag . Questi frammenti di codice visualizzano una finestra del codice e una finestra di output nell'articolo. La finestra di output visualizza qualsiasi output dall'esecuzione del codice interattivo dopo che l'utente ha eseguito il frammento di codice.

L'esperienza interattiva C# cambia il modo in cui vengono usati frammenti di codice. I visitatori possono eseguire il frammento di codice per visualizzare i risultati. Un certo numero di fattori consente di determinare se il frammento di codice o il testo corrispondente deve includere informazioni sull'output.

Quando visualizzare l'output previsto senza eseguire il frammento

• Gli articoli destinati a principianti dovrebbero fornire l'output in modo che i lettori possano confrontare l'output del proprio lavoro con la risposta prevista.
• I frammenti in cui l'output è integrale all'argomento devono visualizzare tale output. Ad esempio, gli articoli sul testo formattato devono mostrare il formato di testo senza eseguire il frammento di codice.
• Quando sia il frammento di codice che l'output previsto sono brevi, è consigliabile visualizzare l'output. per risparmiare tempo.
• Gli articoli che spiegano come le impostazioni cultura o le impostazioni cultura inglese non dipendenti da paese/area geografica influiscono sull'output devono spiegare l'output previsto. Il ciclo Read–Eval–Print interattivo viene eseguito in un host basato su Linux. Le impostazioni cultura predefinite e le impostazioni cultura inglese non dipendenti da paese/area geografica producono output diversi a seconda dei sistemi operativi e dei computer. L'articolo deve spiegare l'output nei sistemi Windows, Linux e Mac.

Quando escludere l'output previsto dal frammento

• Gli articoli in cui il frammento genera un output di dimensioni maggiori non devono includere tale output nei commenti. Nasconde il codice dopo l'esecuzione del frammento.
• Articoli in cui il frammento di codice illustra un argomento, ma l'output non è integrale per comprenderlo. ad esempio un codice che esegue una query LINQ per illustrare la sintassi della query e quindi visualizzare ogni elemento nella raccolta di output.

Contributi a contenuti non in lingua inglese

I contributi per il contenuto tradotto automaticamente non sono attualmente accettati. Per migliorare la qualità del contenuto tradotto automaticamente, è stato effettuato il passaggio a un motore di traduzione automatica neurale. Microsoft accetta e incoraggia i contributi per il contenuto con traduzione umana, usato per il training del motore di traduzione automatica neurale. Nel corso del tempo i contributi per il contenuto tradotto miglioreranno la qualità sia della traduzione umana che della traduzione automatica. Gli argomenti tradotti in modo automatico includeranno una dichiarazione di non responsabilità che informa che parte dell'argomento potrebbe essere tradotta automaticamente e il pulsante Modifica non verrà visualizzato, perché la modifica è disabilitata.

Contratto di licenza per contributi

È necessario firmare il contratto di licenza per contributi di .NET Foundation (CLA) prima che la richiesta pull venga unita. Questa è una procedura da eseguire una volta sola per i progetti in .NET Foundation. Per altre informazioni, vedere Contributor License Agreement (Contratto di licenza per contributi) su Wikipedia.

Contratto: Contratto di licenza collaboratore .NET Foundation (CLA)

Non è necessario firmare il contratto in anticipo. È possibile clonare, creare una copia tramite fork e inviare la richiesta pull come di consueto. Quando viene creata, la richiesta pull è classificata da un bot CLA. Se la modifica è minima (ad esempio, la correzione di un errore ortografico) alla richiesta pull viene assegnata l'etichetta cla-not-required. In caso contrario, viene classificata come cla-required. Una volta che il contratto di licenza per contributi è stato firmato, la richiesta pull attuale e tutte le richieste future sono etichettate come cla-signed.