Mitwirken an den .NET-Dokumentationsrepositorys

Vielen Dank für Ihr Interesse und Ihre Bereitschaft, an der .NET-Dokumentation mitzuwirken!

In diesem Artikel erfahren Sie, wie Sie an Artikeln und Codebeispielen der .NET-Dokumentation mitwirken können. Die Beiträge können so einfach wie das Korrigieren von Tippfehlern oder so komplex wie das Verfassen neuer Artikel sein.

Die .NET-Dokumentationswebsite basiert auf mehreren Repositorys. Dies sind nur einige davon:

Richtlinien für Beiträge

Wir schätzen community Beiträge dokumentation. In der folgenden Liste sind einige Leitregeln aufgeführt, die Sie berücksichtigen sollten, wenn Sie zur .NET-Dokumentation beitragen:

  • NEIN: Überfallen Sie uns nicht mit großen Pull Requests. Eröffnen Sie stattdessen ein Ticket, und starten Sie eine Diskussion, damit wir uns auf eine Richtung einigen können, bevor Sie sehr viel Zeit investieren.
  • SCHLIESSEN SIE KEINEN Beispielcode inline in einen Artikel ein.
  • VERWENDEN SIE ein Codeausschnittprojekt, um es in den Artikel einzubetten.
  • Befolgen Sie diese Anweisungen und die Richtlinien für Sprache und Stil.
  • JA Verwenden Sie die Vorlagendatei als Ausgangspunkt für Ihre Arbeit.
  • JA Erstellen Sie einen separaten Branch in Ihrer Verzweigung, bevor Sie an den Artikeln arbeiten.
  • Befolgen Sie den Workflow für GitHub Flow.
  • Bloggen oder twittern Sie über Ihre Beiträge.

Durch diese Richtlinien wird der Ablauf für Sie und für uns erleichtert.

Beitragsprozess

Schritt 1: Wenn Sie daran interessiert sind, neue Inhalte zu schreiben oder vorhandene Inhalte gründlich zu überarbeiten, öffnen Sie ein Problem , das beschreibt, was Sie tun möchten. Der Inhalt im Dokumentordner ist in Abschnitte unterteilt, die im Inhaltsverzeichnis (Inhaltsverzeichnis) widerzuspiegeln sind. Definieren Sie, an welcher Stelle sich das Thema im Inhaltsverzeichnis befinden wird. Warten Sie auf Feedback zu Ihrem Vorschlag.

Oder

Wählen Sie ein vorhandenes Issue aus, und beheben Sie es. Sie können ebenfalls die Liste open issues (Offene Issues) ansehen und an einem Issue mitwirken, der Sie interessiert.

  • Filtern Sie nach der Bezeichnung good-first-issue, um nach guten ersten Issues zu suchen.
  • Filtern Sie nach der Bezeichnung up-for-grabs, um nach Issues zu suchen, die für einen Communitybeitrag geeignet sind. Diese Issues erfordern in der Regel nur minimalen Kontext.
  • Erfahrene Mitwirkende können beliebige relevante Issues lösen.

Wenn Sie ein entsprechendes Issue finden, fügen Sie einen Kommentar hinzu, um zu fragen, ob es noch offen ist.

Nachdem Sie eine Aufgabe für die Arbeit ausgewählt haben, erstellen Sie ein GitHub-Konto , und fahren Sie mit Schritt 2 fort.

Schritt 2: Verzweigen Sie das /dotnet/docs Repository (oder welches Repository Sie beisteuern) nach Bedarf, und erstellen Sie eine Verzweigung für Ihre Änderungen.

Kleine Änderungen finden Sie unter "Bearbeiten" im Browser.

Schritt 3: Nehmen Sie die Änderungen in diesem neuen Branch vor.

Wenn es sich um ein neues Thema handelt, können Sie diese Vorlagendatei als Ausgangspunkt verwenden. Sie enthält die Richtlinien zum Schreiben und erläutert auch die Metadaten, die für jeden Artikel erforderlich sind (z. B. Informationen zum Autor). Weitere Informationen zur Markdown-Syntax, die in Microsoft Learn-Inhalten verwendet wird, finden Sie in der Markdown-Referenz.

Navigieren Sie zu dem Ordner, der dem für Ihren Artikel in Schritt 1 ermittelten Inhaltsverzeichnisspeicherort entspricht. Dieser Ordner enthält die Markdowndateien für alle Artikel in diesem Abschnitt. Erstellen Sie ggf. einen neuen Ordner für die Dateien mit Ihrem Inhalt. Der Hauptartikel für diesen Bereich wird als index.md bezeichnet.

Erstellen Sie in dem Ordner mit Ihrem Artikel für Bilder und andere statische Ressourcen einen Unterordner namens media (falls dieser nicht bereits vorhanden ist). Erstellen Sie im Ordner media einen Unterordner mit dem Artikelnamen (mit Ausnahme der Indexdatei). Weitere Informationen zum Speicherort Ihrer Dateien finden Sie im Abschnitt Beispielordnerstruktur.

Fügen Sie keinen Code inline in den Artikel ein, es sei denn, Sie demonstrieren ein Konstrukt, das nicht kompiliert wird. Verwenden Sie stattdessen ein Codeausschnittprojekt, und schließen Sie den Code mithilfe der Codeerweiterung ein. Dadurch wird sichergestellt, dass Ihr Beispielcode von unserem CI-System überprüft wird.

Erstellen Sie für Codeausschnitte einen Unterordner namens snippets (Codeausschnitte) in dem Ordner, der Ihren Artikel enthält (falls noch nicht vorhanden). Erstellen Sie im Ordner snippets einen Unterordner mit dem Artikelnamen. In den meisten Fällen haben Sie Codeausschnitte für die wichtigsten drei .NET-Hauptsprachen C#, F# und Visual Basic. Erstellen Sie in diesem Fall Unterordner namens csharp, fsharp und vb für jedes der drei Projekte. Wenn Sie einen Codeausschnitt für einen Artikel unter den Ordnern docs/csharp, docs/fsharp oder docs/visual-basic erstellen, wird der Ausschnitt nur in einer Sprache angezeigt, sodass Sie den Sprachordner weglassen können. Weitere Informationen zum Speicherort Ihrer Dateien finden Sie im Abschnitt Beispielordnerstruktur.

Codeausschnitte sind kleine fokussierte Codebeispiele, die die in diesem Artikel behandelten Konzepte veranschaulichen. Größere Programme, die für den Download und die Durchsuchung vorgesehen sind, sollten sich im dotnet/samples-Repository befinden. Vollständige Beispiele werden im Abschnitt zum Beitrag zu Beispielen behandelt.

Schritt 4: Übermitteln Sie eine Pullanforderung (PR) von Ihrer Verzweigung an die Standardbranch.

Wichtig

Die Kommentarautomatisierung ist derzeit nicht für die Repositorys für die .NET-Dokumentation verfügbar. Die Mitglieder des Teams für die .NET-Dokumentation überprüfen und mergen Ihren Pull Request.

Jeder PR sollte in der Regel jeweils ein Issue behandeln, es sei denn, mehrere Issues beziehen sich auf den gleiche PR-Fix. Mit dem PR können auch mehrere Dateien geändert werden. Wenn Sie sich mit mehreren Korrekturen an verschiedenen Dateien befassen, werden separate PRs bevorzugt.

Wenn Ihr Pull Request ein vorhandenes Problem behebt, fügen Sie das Schlüsselwort Fixes #Issue_Number zur Beschreibung des Pull Requests hinzu. Auf diese Weise wird das Ticket automatisch geschlossen, wenn der Pull Request zusammengeführt wird. Weitere Informationen finden Sie unter Verknüpfen eines Pull Requests mit einem Problem mithilfe eines Schlüsselworts.

Das .NET-Team überprüft Ihren PR und teilt Ihnen mit, ob für die Genehmigung noch weitere Aktualisierungen/Änderungen erforderlich sind.

Schritt 5: Nehmen Sie, wie mit dem Team besprochen, alle erforderlichen Aktualisierungen in Ihrem Branch vor.

Die Verwalter mergen Ihren Pull Request in den Standardbranch, sobald das Feedback umgesetzt und die Änderung genehmigt wurde.

Alle Commits werden mithilfe von Push regelmäßig vom Standardbranch in den Livebranch übertragen. Dann können Sie Ihren Beitrag in der .NET-Dokumentation sehen. Diese Veröffentlichungen finden werktags in der Regel täglich statt.

Beispiel für die Paketordnerstruktur

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 ...

Hinweis

Die Sprachordner unter „snippets“ werden im Sprachleitfaden nicht benötigt. Dort wird nur eine Sprache angenommen. Im C#-Leitfaden wird beispielsweise davon ausgegangen, dass alle Codeausschnitte in der Sprache C# sind.

In der oben dargestellten Struktur ist ein Image enthalten (portability_report.png) sowie drei Codeprojekte, die Codeausschnitte enthalten. Diese Codeausschnitte sind wiederum im Artikel porting-overview.md zu finden.

Der Ordner snippets/shared wird für Codeausschnitte verwendet, die mehrere Artikel innerhalb desselben übergeordneten Ordners umfassen, zum Beispiel den Portierungsordner im vorherigen Beispiel. Verwenden Sie nur den Ordner shared, wenn Sie dafür einen Grund haben, wie etwa XAML-Code, auf den von mehreren Artikeln verwiesen wird und der im artikelspezifischen Ordner nicht kompiliert werden kann.

Medien können auch artikelübergreifend freigegeben werden, wenn sich diese Artikel im selben übergeordneten Ordner befinden, zum Beispiel der Portierungsordner im vorherigen Beispiel. Dieser freigegebene Ordner (shared) sollte nach Möglichkeit vermieden werden, wenn es sinnvoll ist. Es kann beispielsweise sinnvoll sein, einen gemeinsamen Ladebildschirm für die zu demonstrierende App freizugeben oder Visual Studio-Dialoge, die in mehreren Artikeln wiederverwendet werden.

Wichtig

Aus historischen Gründen werden viele der enthaltenen Ausschnitte im Ordner /samples des dotnet/docs-Repositorys gespeichert. Wenn Sie wesentliche Änderungen an einem Artikel vornehmen, sollten diese Ausschnitte in die neue Struktur verschoben werden. Machen Sie sich jedoch keine Gedanken über die Verschiebung von Codeausschnitten für kleinere Änderungen.

Beispiele für die Mitwirkung

Für Code, der unsere Inhalte unterstützt, wird Folgendes unterschieden:

  • Beispiele: Leser können die Beispiele herunterladen und ausführen. Alle Beispiele sollten vollständige Anwendungen oder Bibliotheken sein. Wenn mit dem Beispiel eine Bibliothek erstellt wird, sollte diese Komponententests oder eine Anwendung enthalten, mit der Leser den Code ausführen können. Häufig werden mehrere Technologien, Features oder Toolkits verwendet. Die Datei „readme.md“ für jedes Beispiel verweist auf den Artikel, sodass Sie sich über die Konzepte informieren können, mit denen sich die Beispiele befassen.
  • Codeausschnitte: Sie veranschaulichen ein kleineres Konzept oder eine kleinere Aufgabe. Sie können kompiliert werden, sind aber nicht als vollständige Anwendungen vorgesehen. Sie sollten ordnungsgemäß ausgeführt werden können, sind jedoch keine Beispielanwendungen für ein bestimmtes Szenario. Codeausschnitte sollen so klein wie möglich sein, um ein einzelnes Konzept oder Feature zu veranschaulichen. Dabei sollte nicht mehr Code enthalten sein, als auf einen üblichen Bildschirm passt.

Beispiele befinden sich im Repository dotnet/samples. Wir arbeiten an einem Modell, bei dem die Ordnerstruktur für die Beispiele der Ordnerstruktur für die Dokumente entspricht. Wir richten uns nach folgenden Standards:

  • Die Ordner auf oberster Ebene entsprechen den Ordnern, die sich im Repository docs auf oberster Ebene befinden. Beispiel: Das Repository „docs“ enthält einen Ordner machine-learning/tutorials. Die Beispiele für die Machine Learning-Tutorials befinden sich im Ordner samples/machine-learning/tutorials.

Darüber hinaus sollten alle Beispiele in den Ordnern core und standard auf allen von .NET Core unterstützten Plattformen erstellt und ausgeführt werden können. Das wird durch unser CI-Build-System erzwungen. Der Ordner Framework auf oberster Ebene enthält Beispiele, die nur unter Windows erstellt und validiert werden.

Beispielprojekte sollten dem Szenario entsprechend auf so vielen Plattformen wie möglich ausgeführt können. In der Praxis bedeutet das, dass Sie nach Möglichkeit auf .NET Core basierende Konsolenanwendungen erstellen sollten. Beispielen, die für Web- oder Benutzeroberflächenframeworks gelten, sollten diese Tools bei Bedarf hinzugefügt werden. Dazu zählen unter anderem Webanwendungen, mobile Apps und WPF- oder WinForms-Apps.

Wir arbeiten an einem CI-System für jeden Code. Wenn Sie Beispiele aktualisieren, sollten Sie sicherstellen, dass jedes Update Teil eines erstellbaren Projekts ist. Fügen Sie den Beispielen im Idealfall auch Tests auf Richtigkeit hinzu.

Jedes vollständige Beispiel, das Sie erstellen, sollte eine Datei readme.md enthalten. Diese Datei sollte eine kurze Beschreibung des Beispiels (ein oder zwei Absätze) enthalten. Die Datei readme.md soll dem Leser erläutern, was er durch das Untersuchen dieses Beispiels lernt. Die Datei readme.md sollte auch einen Link zu dem Live-Dokument auf der Website .NET-Dokumentation enthalten. Um zu bestimmen, wenn eine bestimmte Datei im Repository dieser Website zugeordnet ist, ersetzen Sie /docs im Repository-Pfad durch https://learn.microsoft.com/dotnet.

Ihr Thema enthält auch Links zum Beispiel. Erstellen Sie einen direkten Link zum Beispielordner auf GitHub.

Schreiben eines neuen Beispiels

Beispiele sind vollständige Programme und Bibliotheken, die zum Download bereit stehen. Sie sind möglicherweise sehr klein, aber sie veranschaulichen Konzepte auf eine Weise, die es den Benutzern ermöglicht, selbst zu forschen und zu experimentieren. Die Richtlinien für diese Beispiele stellen sicher, dass Leser diese herunterladen und erkunden können. Sehen Sie sich die Beispiele zu Paralleles LINQ (PLINQ) als Beispiel für jede Richtlinie an.

  1. Ihr Beispiel muss Teil eines erstellbaren Projekts sein. Die Projekte sollten nach Möglichkeit auf allen Plattformen erstellt werden können, die von .NET Core unterstützt werden. Davon ausgenommen sind Beispiele, die plattformspezifische Features oder Tools veranschaulichen.

  2. Ihr Beispiel sollte aus Gründen der Konsistenz dem Runtimeprogrammierstil entsprechen.

    Zudem sollten Sie static-Methoden anstelle von Instanzmethoden verwenden, wenn Sie etwas veranschaulichen möchten, für das die Instanziierung von Objekten nicht erforderlich ist.

  3. Ihre Beispiele sollten eine angemessene Ausnahmebehandlung umfassen. Diese sollte alle Ausnahmen behandeln, die im Kontext des Beispiels wahrscheinlich ausgelöst werden. In ein Beispiel, in dem die Methode Console.ReadLine aufgerufen wird, um die Benutzereingabe abzurufen, sollte beispielsweise eine angemessene Ausnahmebehandlung eingefügt werden, die verwendet werden kann, wenn die Eingabezeichenfolge als Argument an eine Methode übergeben wird. Wenn ihr Beispiel erwartet, dass ein Methodenaufruf fehlschlägt, muss ebenfalls die Ausnahme behandelt werden, die ausgelöst wird. Sie sollten immer die Ausnahmen behandeln, die von der Methode ausgelöst werden, nicht die Ausnahmen der Basisklassen wie Exception oder SystemException.

So erstellen Sie ein Beispiel:

  1. Eröffnen Sie ein Issue, oder fügen Sie einen Kommentar zu einem vorhandenen Issue hinzu, der aussagt, dass Sie an diesem arbeiten.

  2. Schreiben Sie einen Artikel, der die Konzepte erläutert, die in Ihrem Beispiel veranschaulicht werden (z.B. docs/standard/linq/where-clause.md).

  3. Schreiben Sie Ihr Beispiel (z.B. WhereClause-Sample1.cs).

  4. Erstellen Sie die Datei „Program.cs“ mit einem Haupteinstiegspunkt, der Ihr Beispiel aufruft. Wenn diese bereits vorhanden ist, fügen Sie den Aufruf zum Beispiel hinzu:

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

Sie erstellen einen beliebigen .NET-Codeausschnitt oder ein Beispiel mit der .NET CLI, der mit dem .NET SDK installiert werden kann. So können Sie ein Beispiel erstellen und ausführen:

  1. Navigieren Sie zum Ordner des Beispiels, und führen Sie „dotnet build“ aus, um diesen auf Fehler zu überprüfen:

    dotnet build
    
  2. Führen Sie Ihr Beispiel aus:

    dotnet run
    
  3. Fügen Sie die Datei „readme.md“ zum Stammverzeichnis Ihres Beispiels hinzu.

    Diese sollte eine kurze Beschreibung des Codes und einen Verweis auf den Artikel enthalten, zu dem das Beispiel gehört. Der obere Bereich der readme.md-Datei muss über die erforderlichen Metadaten für den Beispielbrowser verfügen. Der Headerblock muss folgende Felder enthalten:

    ---
    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
    ---
    
    • Die languages-Sammlung sollte nur die Sprachen enthalten, die für Ihr Beispiel verfügbar sind.
    • Die products-Sammlung sollte nur die für Ihr Beispiel relevanten Produkte enthalten.

Sofern nicht angegeben, erstellen alle Beispiele aus der Befehlszeile auf jeder plattform, die von .NET unterstützt wird. Es gibt einige Beispiele, die speziell für Visual Studio erstellt wurden. Für diese ist Visual Studio 2017 oder höher erforderlich. Außerdem behandeln einige Beispiele plattformspezifische Features. Für diese ist eine bestimmte Plattform erforderlich. Andere Beispiele und Codeausschnitte werden unter Windows ausgeführt und benötigen .NET Framework sowie das Developer Pack für die Zielversion des Frameworks.

Die interaktive C#-Umgebung

Für alle Codeausschnitte, die in einem Artikel enthalten sind, wird ein Sprachtag verwendet, um die Quellsprache anzugeben. Für kurze Codeausschnitte in C# kann das Sprachtag csharp-interactive verwendet werden, um einen C#-Codeausschnitt anzugeben, der im Browser ausgeführt wird. (Für Inlinecodeausschnitte wird das Tag csharp-interactive verwendet und für Codeausschnitte, die über die Quelle hinzugefügt werden, das Tag code-csharp-interactive.) Diese Codeausschnitte stellen im Artikel ein Codefenster und ein Ausgabefenster dar. Das Ausgabefenster zeigt die Ausgabe an, die aus dem interaktiven Code entsteht, sobald der Benutzer den Codeausschnitt ausgeführt hat.

Durch die interaktive C#-Benutzeroberfläche wird das Arbeiten mit Ausschnitten verändert und verbessert. Leser können den Codeausschnitt ausführen, um die Ergebnisse anzuzeigen. Es gibt einige Faktoren, anhand derer Sie entscheiden können, ob der Codeausschnitt oder der zugehörige Text Informationen zur Ausgabe enthalten sollte.

Wann die erwartete Ausgabe ohne Ausführung des Codeausschnitts erkennbar sein sollte

  • In Artikeln, die für Anfänger gedacht sind, sollten die Ausgaben bereitgestellt werden, damit der Leser die Ausgabe bei seiner Arbeit mit der erwarteten Antwort vergleichen kann.
  • In Codeausschnitten, bei denen die Ausgabe eine wichtige Rolle für den Artikel spielt, sollte diese enthalten sein. Bei Artikeln über formatierten Text sollte das Textformat ersichtlich sein, ohne den Codeausschnitt auszuführen.
  • Wenn der Codeausschnitt und die erwartete Ausgabe kurz sind, sollten Sie die Ausgabe ebenfalls einfügen. Das spart ein wenig Zeit.
  • In Artikeln, in denen erläutert wird, wie die aktuelle oder die invariante Kultur die Ausgabe beeinflusst, sollte auch die erwartete Ausgabe erläutert werden. Der interaktive REPL (Read, Evaluate, Print Loop) wird auf einem Linux-basierten Host ausgeführt. Die Standardkultur und die invariante Kultur führen auf verschiedenen Betriebssystemen und Computern zu unterschiedlichen Ausgaben. Der Artikel sollte eine Erläuterung der Ausgabe in Windows-, Linux- und Mac-Systemen enthalten.

Wann die erwartete Ausgabe nicht im Codeausschnitt enthalten sein sollte

  • Bei Artikeln mit einem Codeausschnitt, der eine große Ausgabe generiert, sollte diese nicht in den Kommentaren enthalten sein. Der Code wird dadurch unübersichtlich, sobald der Codeausschnitt ausgeführt wurde.
  • Bei Artikeln mit einem Codeausschnitt, der ein Thema veranschaulicht, bei dem die Ausgabe für das Verständnis nicht relevant ist. Beispiel: Code, der eine LINQ-Abfrage zum Erläutern der Abfragesyntax ausführt und dann jedes Element in der Ausgabeauflistung anzeigt.

Hinweis

Sie werden feststellen, dass einige Artikel den hier ausgeführten Richtlinien nicht entsprechen. Wir arbeiten daran, auf der gesamten Website Konsistenz zu erzielen. Überprüfen Sie in der Liste open issues die offenen Tickets, die wir derzeit für dieses spezielle Ziel verfolgen.

Beiträge zu nicht englischen Inhalten

Beiträge für maschinell übersetzte (MT) Inhalte werden zurzeit nicht akzeptiert. Um die Qualität von MT-Inhalten zu verbessern, haben wir auf eine neuronale MT-Engine umgestellt. Wir akzeptieren und begrüßen Beiträge zu von Menschen übersetzten Inhalten (Human Translated Content – HT-Inhalte), die zum Trainieren der neuronalen MT-Engine verwendet werden. Im Laufe der Zeit werden Beiträge zum HT-Inhalt somit die Qualität von HT und MT verbessern. In maschinell übersetzten Themen wird ein Haftungsausschluss angezeigt, der besagt, dass ein Teil des Themas maschinell übersetzt ist, und die Schaltfläche Bearbeiten wird nicht angezeigt, da die Bearbeitung deaktiviert ist.

Hinweis

Bei den meisten lokalisierten Dokumentationen ist es nicht möglich, diese über GitHub zu bearbeiten oder Feedback über GitHub abzugeben. Um Feedback zu lokalisierten Inhalten zu geben, verwenden Sie https://aka.ms/provide-feedback das Formular.

Lizenzvereinbarung für Mitwirkende

Sie müssen das .NET Foundation Contribution License Agreement (CLA) unterzeichnen, bevor Ihr Pull Request zusammengeführt wird. Dies ist eine einmalige Anforderung für .NET Foundation-Projekte. Auf Wikipedia erfahren Sie mehr über Contributor License Agreements (CLA).

Hier finden Sie die Lizenzvereinbarung: .NET Foundation Contributor License Agreement (CLA)

Sie brauchen die Vereinbarung nicht vorab zu unterzeichnen. Sie können Ihren Pull Request wie gewohnt klonen, verzweigen und übermitteln. Beim Erstellen Ihres Pull Requests wird dieser von einem CLA-Bot klassifiziert. Wenn es sich nur um eine geringfügige Änderung handelt (z.B. das Korrigieren eines Tippfehlers), wird der Pull Request mit cla-not-required gekennzeichnet. Andernfalls wird er als cla-required klassifiziert. Nachdem Sie das CLA unterzeichnet haben, werden die aktuellen und alle zukünftigen Pull Requests mit der Bezeichnung cla-signed versehen.