Přispívání do úložišť dokumentace k .NET

Článek
02/03/2024

Děkujeme za váš zájem o psaní příspěvků do dokumentace k .NET.

Tento dokument vysvětluje postup při psaní příspěvků a přidávání ukázek kódu, které jsou hostované na webu s dokumentací k .NET. Příspěvky můžou být jednoduché, třeba oprava překlepu, nebo složité, třeba nové články.

Web dokumentace k .NET je sestavený z více úložišť. Toto jsou jen některé z nich:

Pokyny pro příspěvky

Vážíme si příspěvků komunity do dokumentace. Následující seznam obsahuje některá pravidla, která vás zajímají, když přispíváte do dokumentace k .NET:

NEPŘEKVAPUJTE NÁS rozsáhlými žádostmi o přijetí změn. Než budete něčemu věnovat hodně času, zadejte problém a zahajte diskusi, abychom se mohli předem dohodnout na postupu.
Nezahrnujte vzorový kód vložený do článku.
Do use a fragment project with code to be embedded in the article.
DODRŽUJTE tyto pokyny a pokyny týkající se způsobu vyjadřování.
POUŽÍVEJTE jako výchozí bod své práce soubor se šablonou.
VYTVOŘTE ve svém forku samostatnou větev dřív, než začnete pracovat na článcích.
DODRŽUJTEtok GitHubu.
BLOGUJTE A TWEETUJTE (nebo jinak komunikujte) o svých příspěvcích, pokud chcete.

Dodržením těchto pokynů usnadníte práci sobě i nám.

Proces přispívání

Krok 1: Pokud chcete psát nový obsah nebo důkladně revidovat stávající obsah, otevřete problém popisující, co chcete udělat. Obsah ve složce dokumentace je uspořádaný do oddílů, které se projeví v obsahu (TOC). Určete, kde se má téma v obsahu nacházet. Získejte ke svému návrhu zpětnou vazbu.

nebo

Zvolte existující problém a vyřešte ho. Můžete si prohlédnout seznam otevřených problémů a dobrovolně pracovat na těch, které vás zajímají:

Filtrováním podle popisku good-first-issue si můžete vyfiltrovat tzv. „dobré první problémy“.
Filtrováním podle popisku up-for-grabs si můžete vyfiltrovat problémy, které jsou vhodné pro příspěvky od komunity. Tyto problémy obvykle vyžadují minimální kontext.
Zkušení přispěvatelé můžou řešit jakékoliv problémy, které je zajímají.

Když najdete problém, na kterém chcete pracovat, přidejte komentář s dotazem, jestli je otevřený.

Jakmile vyberete úkol, na který chcete pracovat, vytvořte účet GitHubu a přejděte ke kroku 2.

Krok 2: Vytvořte fork /dotnet/docs úložiště (nebo podle toho, do kterého úložiště přispíváte) podle potřeby a vytvořte větev pro vaše změny.

Malé změny najdete v tématu Úpravy v prohlížeči.

3. krok: Proveďte změny v této nové větvi.

Pokud je téma nové, použijte jako výchozí bod tento soubor se šablonou. Obsahuje pokyny k psaní a vysvětluje metadata, která jsou ke každému článku potřeba, například informace o autorovi. Další informace o syntaxi Markdownu použité v obsahu Microsoft Learn najdete v referenčních informacích k Jazyku Markdown.

Přejděte do složky odpovídající umístění obsahu určeného pro váš článek v kroku 1. V této složce jsou soubory v jazyce Markdown všech článků v tomto oddílu. Pokud je to potřeba, vytvořte novou složku, do které umístíte soubory se svým obsahem. Hlavní článek v tomto oddílu se jmenuje index.md.

Pro obrázky a další statické prostředky vytvořte podsložku nazvanou media (pokud ještě neexistuje) a dejte ji do složky se svým článkem. Ve složce media vytvořte podsložku s názvem článku (kromě souboru indexu). Další informace o umístění souborů najdete v části Příklad struktury složek.

Nezahrnujte kód vložený do článku, pokud neukazujete konstruktor, který se nekompiluje. Místo toho použijte projekt fragmentů kódu a zahrňte kód pomocí rozšíření kódu. Tím zajistíte, že náš systém CI ověří váš vzorový kód.

Pro fragmenty kódu vytvořte podsložku s názvem snippets (pokud ještě neexistuje) a umístěte ji do složky se svým článkem. Ve složce snippets vytvořte podsložku s názvem článku. Ve většině případů budete mít fragmenty kódu pro všechny tři hlavní jazyky .NET (C#, F# a Visual Basic). V takovém případě vytvořte podsložky nazvané csharp, fsharp a vb pro každý ze tří projektů. Pokud vytváříte fragment kódu pro článek ve složce docs/csharp, docs/fsharp nebo docs/visual-basic, bude fragment kódu jenom v jednom jazyce, takže můžete podsložku jazyka vynechat. Další informace o umístění souborů najdete v části Příklad struktury složek.

Fragmenty kódu jsou malé a cílené příklady kódu, které demonstrují koncepty probírané článku. Větší programy, které jsou určeny pro stažení a průzkum, by měly být umístěny v úložišti dotnet/samples. Úplné ukázky jsou uvedeny v části s příspěvky do ukázek kódu.

Krok 4: Odešlete žádost o přijetí změn z vaší větve do výchozí větve.

Důležité

V této chvíli není v úložištích dokumentace k .NET dostupná funkce automatických komentářů. Vaši žádost o přijetí změn zkontrolují členové týmu pro dokumentaci k .NET a sloučí ji.

Každá žádost o přijetí změn by měla obvykle řešit jeden problém najednou, pokud s opravou žádosti o přijetí změn nesouvisí více problémů. Žádost o přijetí změn se může týkat změny jednoho nebo několika souborů. Pokud řešíte více oprav, které se týkají různých souborů, použijte raději samostatné žádosti o přijetí změn.

Pokud vaše žádost o přijetí změn opraví existující problém, přidejte Fixes #Issue_Number klíčové slovo do popisu žádosti o přijetí změn. Když ho přidáte, problém se po sloučení žádosti o přijetí změn automaticky uzavře. Další informace najdete v tématu Propojení žádosti o přijetí změn s problémem pomocí klíčového slova.

Tým .NET zkontroluje vaši žádost o přijetí změn a bude vás informovat, jestli jsou před schválením potřeba další aktualizace nebo změny.

5. krok: Proveďte ve větvi potřebné aktualizace, které jste projednali s týmem.

Správci vaši žádost o přijetí změn sloučí do výchozí větve, jakmile se použije zpětná vazba a vaše změna se schválí.

Do živé větve pravidelně odesíláme všechna potvrzení z výchozí větve a pak uvidíte svůj příspěvek živě v dokumentaci k .NET. Během pracovního týdne změny většinou publikujeme každý den.

Příklad struktury složek

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

Poznámka:

Složky jazyka v oddíle snippets nejsou v oblasti pokynů pro jazyk potřeba, pokud se předpokládá jenom jeden jazyk. V průvodci jazykem C# se například předpokládá, že všechny fragmenty kódu jsou C#.

Struktura uvedená výše zahrnuje jeden obrázek, portability_report.png, a tři projekty kódu, které obsahují fragmenty kódu zahrnuté v článku porting-overview.md.

Fragmenty kódu nebo sdílená složka se používají pro fragmenty kódu, které můžou zahrnovat více článků ve stejné nadřazené složce, jako je například složka přenosu v předchozím příkladu. Sdílenou složku používejte jenom v případě, že máte konkrétní důvod, například kód XAML, na který odkazuje více článků, ale ve složce specifické pro článek se nedá zkompilovat.

Multimédia se dají sdílet i v článcích, když jsou tyto články ve stejné nadřazené složce, jako je například složka přenosu v předchozím příkladu. Tato sdílená složka by se měla v případě potřeby vyhnout a používat pouze tehdy, když dává smysl. Může například dávat smysl sdílet společnou obrazovku načítání pro demonstrovanou aplikaci nebo sdílet dialogová okna sady Visual Studio, která se znovu používají v několika článcích.

Důležité

Z historických důvodů se mnoho zahrnutých fragmentů ukládá do složky /samples v úložišti dotnet/docs. Pokud provádíte v článku zásadní změny, měli byste tyto fragmenty přesunout do nové struktury. Nemějte ale obavy o přesun fragmentů pro malé změny.

Příspěvky do ukázek kódu

Kód, který podporuje náš obsah, rozdělujeme do těchto skupin:

Ukázky: Čtenáři si je můžou stáhnout a spustit. Všechny ukázky musí představovat celé aplikace nebo knihovny. Pokud ukázka vytvoří knihovnu, musí obsahovat testy jednotek nebo aplikaci, která uživatelům umožní kód spustit. Ukázky často používají více technologií, funkcí nebo sad nástrojů. Soubor readme.md, který je u každé ukázky, odkazuje na článek, kde si můžete přečíst další informace o probírané látce.
Fragmenty kódu: Ilustrují menší prvek nebo úlohu. Jsou kompilovatelné, ale nejde o kompletní aplikace. Měly by běžet správně, i když nejde o ukázkovou aplikaci pro typický scénář. Jsou navržené tak, aby byly co nejmenší a ilustrovaly jednu určitou problematiku nebo funkci. Neměly by být delší než jedna obrazovka kódu.

Ukázky jsou uloženy v úložišti dotnet/samples. Pracujeme na modelu, ve kterém bude struktura složek s ukázkami odpovídat struktuře složek dokumentace. Dodržujeme tato pravidla:

Složky nejvyšší úrovně odpovídají nejvyšším složkám v úložišti docs. Například v úložišti docs je složka machine-learning/tutorials a ukázky ke kurzům věnovaným strojovému učení jsou ve složce samples/machine-learning/tutorials.

Navíc všechny ukázky ve složkách core a standard se musí dát vytvořit a spustit na všech platformách, které podporuje .NET Core. To zajistí náš systém sestavení CI. Nejvyšší složka framework obsahuje ukázky, které jsou vytvořené a ověřené jen ve Windows.

Ukázkové projekty se mají dát vytvořit a spustit na co nejvíce platformách. V praxi to znamená, že pokud je to možné, je potřeba vytvářet konzolové aplikace založené na .NET Core. Pokud se ukázky týkají určité webové nebo uživatelské platformy, měli byste podle potřeby přidat i tyto nástroje. Příkladem jsou webové aplikace, mobilní aplikace, aplikace WPF nebo WinForms apod.

Pracujeme na tom, abychom pro všechen kód mohli používat systém CI. Při aktualizaci ukázek dbejte na to, aby každá aktualizace byla součástí sestavitelného projektu. Ideálně přidejte k ukázkám také testy správnosti.

Každá hotová ukázka, kterou vytvoříte, má obsahovat soubor readme.md. V tomto souboru by měl být krátký popis ukázky (jeden nebo dva odstavce). Ze souboru readme.md by se čtenáři měli dozvědět, co se naučí, když si tuto ukázku vyzkouší. V souboru readme.md má být také odkaz na živý dokument na webu s dokumentací k .NET. Pokud chcete zjistit mapování daného souboru v úložišti na tento web, nahraďte /docs v cestě k úložišti adresou https://learn.microsoft.com/dotnet.

Odkaz na ukázku bude i ve vašem tématu. Vytvořte odkaz přímo na složku s ukázkou na GitHubu.

Vytvoření nové ukázky

Ukázky jsou úplné programy a knihovny určené ke stažení. Možná jsou svým rozsahem malé, ale demonstrují koncepty způsobem, který umožňuje, aby si je uživatelé sami prozkoumali a experimentovali s nimi. Pokyny k ukázkám zajišťují, že si uživatelé mohou ukázky stáhnout a prozkoumat. Jako příklad jednotlivých pokynů si projděte si ukázky Parallel LINQ (PLINQ).

Vaše ukázka musí být součástí sestavitelného projektu. Pokud je to možné, měly by být projekty sestavitelné na všech platformách, které podporuje .NET Core. Výjimkou jsou ukázky, které předvádějí funkce určité platformy, nebo nástroj, který se používá jenom pro určitou platformu.
Vaše ukázka by měla odpovídat stylu kódování za běhu, aby se zachovala konzistence.

V ukázkách, ve kterých se nevyžaduje vytvoření instance nového objektu, také raději používáme metody static místo instancí metod.
Vaše ukázka by měla mít náležitě ošetřeny výjimky. V ukázce by měly být ošetřeny všechny výjimky, které se v této souvislosti můžou vyskytnout. Například v ukázce, ve které se načítá uživatelský vstup voláním metody Console.ReadLine, musí být náležitě ošetřena výjimka, kdy se vstupní řetězec předá metodě jako argument. Podobně platí, že pokud se v ukázce předpokládá, že volání metody způsobí chybu, musíte výslednou výjimku ošetřit. Vždy ošetřete konkrétní výjimky způsobené metodou místo výjimek základních tříd, jako je Exception nebo SystemException.

Postup vytvoření ukázky:

Zadejte problém nebo přidejte komentář ke stávajícímu problému a uveďte, že na něm pracujete.
Napište téma a vysvětlete v něm, co v ukázce předvádíte (příklad: docs/standard/linq/where-clause.md).
Napište ukázku (příklad: WhereClause-Sample1.cs).

Vytvořte soubor Program.cs s hlavním vstupním bodem, který volá vaše ukázky. Pokud soubor existuje, přidejte do něj volání své ukázky:

public class Program
{
    public void Main(string[] args)
    {
        WhereClause1.QuerySyntaxExample();

        // Add the method syntax as an example.
        WhereClause1.MethodSyntaxExample();
    }
}

Všechny fragmenty kódu nebo ukázky .NET sestavíte pomocí rozhraní příkazového řádku .NET, které je možné nainstalovat se sadou .NET SDK. Postup vytvoření a spuštění ukázky:

Přejděte do ukázkové složky a zkontrolujte chyby tím, že program zkompilujete:
```
dotnet build
```
Spusťte ukázku:
```
dotnet run
```
Do kořenové složky ukázky přidejte soubor readme.md.

Soubor by měl obsahovat stručný popis kódu a měl by uživatele odkázat na článek, který se ukázky týká. Horní část souboru readme.md musí obsahovat metadata vyžadovaná prohlížečem ukázek. Blok záhlaví musí obsahovat následující pole:
```
---
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
---
```
- Kolekce languages musí zahrnovat jen jazyky, které jsou pro vaši ukázku dostupné.
- Kolekce products musí zahrnovat jen produkty, které jsou pro vaši ukázku relevantní.

Pokud není uvedeno, všechny ukázky se sestavují z příkazového řádku na libovolné platformě podporované platformou .NET. Některé ukázky jsou určené konkrétně pro Visual Studio, a proto vyžadují Visual Studio 2017 nebo novější verzi. Jiné ukázky předvádějí funkce určité platformy, a proto vyžadují určitou platformu. Další ukázky a fragmenty kódu vyžadují rozhraní .NET Framework. Půjdou spustit na platformě Windows, ale budou potřebovat sadu Developer Pack pro verzi cílové architektury.

Interaktivní prostředí jazyka C#

Všechny fragmenty kódu zahrnuté v článku používají značku jazyka k označení zdrojového jazyka. Krátké fragmenty kódu v jazyce C# můžou použít csharp-interactive značku jazyka k určení fragmentu kódu jazyka C#, který se spustí v prohlížeči. (Vložené fragmenty kódu používají csharp-interactive značku, pro fragmenty kódu zahrnuté ze zdroje použijte code-csharp-interactive značku.) Tyto fragmenty kódu zobrazují okno kódu a výstupní okno v článku. V okně výstupu se zobrazí jakýkoli výstup spuštění interaktivního kódu, jakmile uživatel spustí fragment kódu.

Interaktivní prostředí jazyka C# mění způsob práce s fragmenty kódu. Návštěvníci můžou fragment kódu spustit a zobrazit výsledky. Řada faktorů pomáhá určit, jestli má fragment kódu nebo odpovídající text obsahovat informace o výstupu.

Kdy zobrazit očekávaný výstup bez spuštění fragmentu kódu

Výstup by měly obsahovat články, které jsou určené začátečníkům, aby čtenáři mohli porovnat svůj výstup s očekávanou odpovědí.
Fragmenty kódu, kde je výstup nedílnou součástí tématu, by měl tento výstup zobrazit. Například články s formátovaným textem by měly zobrazovat formát textu bez spuštění fragmentu kódu.
Pokud je fragment i očekávaný výstup krátký, zvažte zobrazení výstupu. Trochu to šetří čas.
Očekávaný výsledek by také měl být popsaný v článcích, které vysvětlují vliv aktuální jazykové verze nebo invariantní jazykové verze na výstup. Interaktivní prostředí REPL (Read Evaluate Print Loop) běží na linuxovém hostiteli. Výchozí jazyková verze a invariantní jazyková verze vytvářejí v různých operačních systémech a na různých počítačích odlišné výstupy. V článku by měl být popsaný výstup v systémech Windows, Linux a Mac.

Kdy vyloučit očekávaný výstup z fragmentu kódu

Články, ve kterých fragment kódu generuje větší výstup, by neměl obsahovat v komentářích. Kód po spuštění fragmentu zakrývá.
Články, ve kterých fragment kódu ukazuje téma, ale výstup není nedílnou součástí jeho pochopení. Pokud třeba kód spustí dotaz LINQ kvůli vysvětlení syntaxe dotazu a pak zobrazí každou položku výstupní kolekce.

Poznámka:

Možná jste si všimli, že v současnosti některá témata nedodržují všechny uvedené pokyny. Pracujeme na tom, aby měl web konzistentní podobu. Můžete se podívat na seznam otevřených problémů, které k tomuto cíli v současnosti evidujeme.

Přispívání do neanglických obsahu

Příspěvky spočívající ve strojově přeloženém obsahu (MT) se aktuálně nepřijímají. V rámci úsilí o zvyšování kvality strojově přeloženého obsahu jsme přešli na modul pro neurální MT. Přijímáme a doporučujeme využívat příspěvky přeložené člověkem (HT), na jejichž základě se trénuje modul pro neurální MT. V průběhu času tak budou člověkem přeložené příspěvky vylepšovat kvalitu obsahu v kvalitě HT i MT. Témata v kvalitě MT budou zahrnovat upozornění, že část textu může být strojově přeložená, a tlačítko Upravit se nezobrazí, protože úpravy jsou zakázané.

Poznámka:

Většina lokalizovaných dokumentace nenabízí možnost upravovat ani poskytovat zpětnou vazbu prostřednictvím GitHubu. Pokud chcete poskytnout zpětnou vazbu k lokalizovaného obsahu, použijte https://aka.ms/provide-feedback formulář.

Licenční smlouva s přispěvatelem

Před sloučením žádosti o přijetí změn musíte podepsat licenční smlouvu s přispěvatelem (CLA) pro .NET Foundation. Jde o jednorázový požadavek u projektů pro .NET Foundation. Další informace o licenční smlouvě s přispěvatelem (CLA) najdete na wikipedii.

Smlouva: Licenční smlouva s přispěvatelem .NET Foundation (CLA)

Smlouvu nemusíte podepisovat předem. Žádosti o přijetí změn můžete obvyklým způsobem klonovat, odeslat nebo můžete vytvořit fork. Vytvořenou žádost o přijetí změn klasifikuje robot CLA. Pokud se jedná o malou změnu (třeba o opravu překlepu), bude žádost označena cla-not-required. V ostatních případech bude zařazena jako cla-required. Po podpisu smlouvy CLA budou všechny současné i budoucí žádosti o přijetí změn označeny cla-signed.

Přispívání do úložišť dokumentace k .NET

Pokyny pro příspěvky

Proces přispívání

Příklad struktury složek

Příspěvky do ukázek kódu

Vytvoření nové ukázky

Interaktivní prostředí jazyka C#

Kdy zobrazit očekávaný výstup bez spuštění fragmentu kódu

Kdy vyloučit očekávaný výstup z fragmentu kódu

Přispívání do neanglických obsahu

Licenční smlouva s přispěvatelem

Váš názor

Váš názor

Další materiály