Közreműködés a .NET dokumentációs adattáraihoz

Köszönjük, hogy érdeklődik a .NET-dokumentáció tárházaiban való közreműködés iránt!

Ez a dokumentum azt mutatja be, hogyan működhet közre a .NET-dokumentáció webhelyén tárolt cikkek és kódminták készítésében. A közreműködés módja olyan egyszerű is lehet, mint például egy elgépelés kijavítása, vagy olyan összetett is, mint például egy új cikk írása.

A .NET dokumentációs webhelye több adattárból készült. Ezek csak néhány közülük:

• .NET-fogalmakról szóló cikkek és kódrészletek
• Kódminták és -részletek
• .NET API-referencia
• A .NET Compiler Platform SDK-referenciája
• Az ML.NET API-referenciája

Közreműködési irányelvek

Nagyra értékeljük a dokumentációban való közösségi közreműködést. Az alábbi lista néhány, a .NET-dokumentációhoz való hozzájáruláskor szem előtt tartandó irányadó szabályt tartalmaz:

• NE lepjen meg minket nagy lekéréses kérelmekkel. Inkább vesse fel a témát, és kezdeményezzen párbeszédet, hogy megegyezhessünk egy irányvonalban, mielőtt sok időt áldozna rá.
• NE tartalmazzon beágyazott kódmintát egy cikkben.
• DO használjon kódrészletes projektet a cikkbe ágyazandó kóddal.
• TARTSA BE ezeket az utasításokat, és a stílusra és hangvételre vonatkozó irányelveket.
• HASZNÁLJA a sablon fájlt munkája kiindulási pontjaként.
• HOZZON LÉTRE külön ágat saját elágazásán belül, mielőtt dolgozni kezd a cikkeken.
• KÖVESSE a GitHub-munkafolyamatot.
• ÍRJON blogbejegyzést, tweetet, vagy bármi hasonlót közreműködéseiről.

Ezeknek az irányelveknek a betartása Önnek és nekünk is jobb élményt biztosít.

Hozzájárulási folyamat

1. lépés: Ha új tartalom írása vagy a meglévő tartalom alapos felülvizsgálata érdekli, nyisson meg egy problémát , amely leírja, hogy mit szeretne tenni. A dokumentummappában lévő tartalom a tartalomjegyzékben (TOC) tükröződő szakaszokba van rendezve. Adja meg, hogy hol helyezkedik majd el a témakör a tartalomjegyzékben. Ajánlatáról visszajelzést kap.

-vagy-

Válasszon ki egy meglévő problémát, és foglalkozzon vele. Megtekintheti a nyitott témák listáját is, és jelentkezhet egy olyanra, amely felkelti érdeklődését:

• Szűrjön a jó első probléma címkéje alapján a jó első problémákra.
• Szűrjön a segélyszolgálat címkéje alapján a közösségi hozzájárulásnak megfelelő problémákra. Ezekhez a problémákhoz általában minimális mennyiségű kontextusra van szükség.
• A tapasztalt közreműködők bármilyen fontos problémát meg tudnak oldani.

Ha talál egy kijavítandó problémát, megjegyzésben kérdezze meg, hogy a téma nyitott-e.

Miután kiválasztott egy feladatot, amelyen dolgozni szeretne, hozzon létre egy GitHub-fiókot, és lépjen tovább a 2. lépésre.

2. lépés: Szükség szerint elágaztathatja az /dotnet/docs adattárat (vagy azt, amelyikhez hozzájárul), és létrehozhat egy ágat a módosításokhoz.

Kisebb módosításokért lásd : Szerkesztés a böngészőben.

3. lépés: Végezze el a módosításokat ebben az új ágban.

Ha a témakör új, akkor kiindulásként használhatja ezt a sablon fájlt. Ez tartalmazza az írásra vonatkozó irányelveket, és ismerteti az egyes cikkekhez szükséges olyan metaadatokat, mint a szerző adatai. A Microsoft Learn-tartalmakban használt Markdown-szintaxisról további információt a Markdown-referencia tartalmaz.

Keresse meg azt a mappát, amely megfelel az 1. lépésben a cikkhez meghatározott TOC-helynek. Ez a mappa tartalmazza a szakasz összes cikkéhez tartozó Markdown-fájlokat. Szükség esetén hozzon létre új mappát a tartalomhoz tartozó fájlok elhelyezéséhez. A szakasz fő cikkének neve index.md.

Ha még nem létezik, a képek és más statikus források számára hozzon létre egy media nevű almappát a cikkét tartalmazó mappában. A media mappában hozzon létre almappát a cikk nevével (kivéve az indexfájlt). A fájlok helyével kapcsolatos további információkért tekintse meg a Példa mappaszerkezet című szakaszt.

Ne tartalmazzon beágyazott kódot a cikkben, hacsak nem fordítható szerkezetet mutat be. Ehelyett használjon kódrészleteket tartalmazó projektet, és foglalja bele a kódot a kódbővítmény használatával. Ez biztosítja, hogy a mintakódot a CI-rendszer érvényesítse.

Ha még nem létezik, a kódrészletek számára hozzon létre egy részletek nevű almappát a cikkét tartalmazó mappában. A kódrészletek mappában hozzon létre almappát a cikk nevével. A legtöbb esetben lesznek kódrészletek mindhárom fontos .NET-nyelvhez: a C#-hoz, az F#-hoz és a Visual Basichez. Ebben az esetben hozzon létre csharp, FSharpés VB nevű almappákat a három projekt mindegyikéhez. Ha egy cikkhez a docs/csharp, docs/fsharp vagy docs/visual-basic mappában hoz létre kódrészletet, az csak egy nyelven lesz elérhető, így Ön kihagyhatja a nyelvre vonatkozó almappát. A fájlok helyével kapcsolatos további információkért tekintse meg a Példa mappaszerkezet című szakaszt.

A kódrészletek kis méretű, célzott, a cikkben szereplő fogalmakat bemutató kódok. A letöltésre és ismerkedésre szánt nagyobb programok a DotNet/Samples adattárban találhatók. A teljes mintákat a Közreműködés a mintákhoz című szakaszban találja.

4. lépés: Lekéréses kérelem (PR) elküldése az ágból az alapértelmezett ágba.

Minden lekéréses kérelemnek általában egyszerre egy problémával kell foglalkoznia, kivéve, ha több probléma kapcsolódik ugyanahhoz a pr-javításhoz. A lekéréses kérelem egy vagy több fájlt is módosíthat. Ha több javítással foglalkozik különböző fájlokban, akkor előnyösebb külön lekéréses kérelmeket küldeni.

Ha a lekéréses kérelem kijavít egy meglévő problémát, adja hozzá a Fixes #Issue_Number kulcsszót a lekéréses kérelem leírásához. A téma így automatikusan le lesz zárva a lekéréses kérelem egyesítésekor. További információ: Lekéréses kérelem csatolása kulcsszóval kapcsolatos problémához.

A .NET-csapat elbírálja lekéréses kérelmét, és értesíti önt, ha a jóváhagyásához további frissítésre/módosításra van szükség.

5. lépés: Végezzen el minden szükséges frissítést az ágában, a csapattal egyeztetett módon.

A karbantartók a visszajelzés alkalmazása és a módosítás jóváhagyása után egyesítik a pr-t az alapértelmezett ágba.

Rendszeresen leküldjük az alapértelmezett ág összes véglegesítését az élő ágba, majd élőben láthatja a közreműködését a .NET dokumentációjában. A közzétételt munkanapokon általában naponta hajtjuk végre.

Példamappa szerkezete

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

A fent látható struktúra a portability_report.png képet és három olyan programkód-projektet tartalmaz, amelyek olyan kódrészleteket tartalmaznak, amelyek megtalálhatók a porting-overview.md cikkben.

A kódrészletek/megosztott mappák olyan kódrészletekhez használatosak, amelyek több cikket is lefedhetnek ugyanabban a szülőmappában, például az előző példában szereplő portolómappát . Csak akkor használja a megosztott mappát, ha erre van egy konkrét oka, például a több cikk által hivatkozott XAML-kód, de nem tud lefordítani a cikkspecifikus mappában.

A médiatartalmak akkor is megoszthatók cikkek között, ha ezek a cikkek ugyanabban a szülőmappában találhatók, például az előző példában lévő portolómappában . Ezt a megosztott mappát lehetőség szerint kerülni kell, és csak akkor kell használni, ha van értelme. Érdemes lehet például megosztani egy közös betöltési képernyőt a bemutatott alkalmazáshoz, vagy megosztani a Visual Studio több cikkben újrahasznált párbeszédpaneleit.

Közreműködés a mintákban

A tartalmunkat támogató kódokat az alábbiak szerint különböztetjük meg:

• Minták: az olvasók letölthetik és futtathatják a mintákat. Minden mintának teljes alkalmazásnak vagy kódtárnak kell lennie. Ha a minta kódtárat hoz létre, annak egységteszteket, vagy olyan alkalmazást is magában kell foglalnia, amellyel az olvasók futtatni tudják a kódot. Gyakran több technológiát, funkciót vagy eszközkészletet is felhasználnak. Az egyes mintákhoz tartozó readme.md fájl hivatkozik a cikkre, így tovább tájékozódhat a minták által bemutatott fogalmakról.
• Kódrészletek: kisebb fogalmat vagy feladatot mutatnak be. Lefordíthatók, de nem teljes alkalmazásnak szánjuk őket. Helyesen kell futniuk, de nem egy jellemző helyzetre példát mutató alkalmazások. A tervezésük szempontja inkább az, hogy minél kisebb méretben mutassanak be egy fogalmat vagy funkciót. A kódnak el kell férnie egy képernyőn.

A minták a dotnet/samples adattárban találhatók. Dolgozunk egy olyan modellen, amelyben a minták mappastruktúrája megfeleltethető a dokumentumok mappastruktúrájával. A követett szabványok a következők:

• A legfelső szintű mappák a docs adattár legfelső szintű mappáival egyeznek meg. A docs adattárban például van egy machine-learning/tutorials mappa, a gépi tanulási oktatóanyagok pedig a samples/machine-learning/tutorials mappában vannak.

Ezen felül a core és a standard mappák alatti összes mintának lefordíthatónak és futtathatónak kell lennie a .NET Core által támogatott összes platformon. Erről CI build-rendszerünk gondoskodik. A legfelső szintű framework (keretrendszer) mappa olyan mintákat tartalmaz, amelyek csak Windows rendszerre készültek, és azon lettek ellenőrizve.

A mintaprojekteknek a platformok adott minta esetén elképzelhető legszélesebb körén lefordíthatóknak és futtathatónak kell lenniük. A gyakorlatban ez .NET Core-alapú konzolalkalmazások készítését jelenti, ha csak lehetséges. A kimondottan webes, vagy egy felhasználói felülethez készült mintáknak a szükséges eszközöket is meg kell adniuk. Ilyenek például a webes alkalmazások, a mobilalkalmazások, a WPF- vagy WinForms-alkalmazások, és sok más.

Dolgozunk azon, hogy minden kódhoz rendelkezésre álljon CI-rendszer. Amikor mintákat frissít, gondoskodjon arról, hogy minden frissítés a lefordítható projekt része legyen. A legjobb, ha a helyes működést ellenőrző teszteket is ad a mintákhoz.

Minden létrehozott teljes mintának tartalmaznia kell egy readme.md fájlt. Ennek a fájlnak a minta rövid (egy-két bekezdés terjedelmű) leírását is tartalmaznia kell. Az olvasók a readme.md fájlból tudják meg, hogy mit ismerhetnek meg a minta vizsgálatával. A readme.md fájlnak egy hivatkozást is tartalmaznia kell a .NET dokumentációjának webhelyén lévő élő dokumentumra. Azt, hogy egy adott fájl az adattárban erre a webhelyre lesz leképezve úgy ellenőrizheti, hogy az adattár elérési útjában a https://learn.microsoft.com/dotnet címet írja a /docs helyére.

A témakörnek a mintára mutató hivatkozásokat is tartalmaznia kell. Hivatkozzon közvetlenül a minták mappájára GitHubon.

Új minta írása

A minták a letöltésre szánt teljes programok és kódtárak. Ezek általában kicsik, de a fogalmakat olyan módon mutatják be, amely lehetővé teszi, hogy a felhasználók saját maguk is megismerjék és kísérletezzenek vele. A mintákra vonatkozó irányelvek biztosítják, hogy az olvasók letölthessék és megismerhessék azokat. Az egyes irányelvekre példaként tekintse át a Párhuzamos LINQ (PLINQ) mintákat.

1. A mintának egy lefordítható projekt részének kell lennie. Ha csak lehetséges, a projektek legyenek a .NET Core által támogatott összes platformon lefordíthatók. Ez alól csak a platformspecifikus funkciót vagy platformspecifikus eszközt bemutató minták kivételek.

2. A konzisztencia fenntartása érdekében a mintának meg kell felelnie a futtatókörnyezet kódolási stílusának .

   Példánymetódusok helyett előnyösebb static metódusokat használni, ha olyasmit mutat be, ami nem igényli új objektumpéldány létrehozását.

3. A mintának megfelelő kivételkezelést is tartalmaznia kell. Ennek minden olyan kivételt kezelnie kell, amely feltehetően előfordul a minta környezetében. A felhasználói adatbevitel bekérésére a Console.ReadLine metódust hívó mintának például a megfelelő kivételkezelést kell használnia, amikor a bemeneti sztring argumentumként át van adva a metódusnak. Ugyanígy, ha a mintában egy metódus sikertelen hívása várható, a keletkező kivételt is kezelni kell. Mindig a metódus által okozott adott kivételt kell kezelni, és nem az olyan, alaposztályokba tartozó kivételeket, mint az Exception vagy a SystemException.

Minta létrehozása:

1. Jelentsen be egy témát, vagy fűzzön megjegyzést egy meglévőhöz arról, hogy azzal dolgozik.

2. Írja meg a témakört, amely a minta által bemutatott fogalmakat magyarázza el (például: docs/standard/linq/where-clause.md).

3. Írja meg a mintát (például: WhereClause-Sample1.cs).

4. Hozzon létre egy Program.cs fájlt, a mintáit meghívó Main belépési ponttal. Ha már van ilyen, akkor szúrja be a mintája hívását:

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

Bármilyen .NET-kódrészletet vagy -mintát a .NET CLI használatával hozhat létre, amely a .NET SDK-val telepíthető. A minta fordítása és futtatása:

1. Lépjen a minták mappájába, és hibakeresés céljából végezzen buildelést:

   dotnet build
   

2. Futtassa le a kódot:

   dotnet run
   

3. Adjon hozzá egy readme.md fájlt a minta gyökérmappájához.

   Ennek tartalmaznia kell a kód tömör leírását, és meg kell adnia a kódra hivatkozó cikket. A readme.md legelején meg kell adni azokat a metaadatokat, amelyek a mintaböngészőhöz szükségesek. A fejléc blokkjának a következő mezőket kell tartalmaznia:

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

   • A languages gyűjteménynek csak a mintában elérhető nyelveket szabad tartalmaznia.
   • A products gyűjteménynek csak a mintához releváns termékeket szabad tartalmaznia.

A feljegyzett esetek kivételével minden minta a parancssorból épül fel a .NET által támogatott platformokon. Néhány minta kimondottan a Visual Studióhoz készült, és a Visual Studio 2017 vagy újabb verzióját igényli. Néhány példa ezen felül platformspecifikus funkciókat is bemutat, és egy adott platformot igényel. Más minták és kódrészletek a .NET-keretrendszert igénylik, Windows-platformokon futnak, és szükség van hozzájuk a célzott keretrendszer-verzió fejlesztői csomagjára.

Az interaktív C# felület

A cikkben szereplő összes kódrészlet nyelvcímkével jelzi a forrásnyelvet. A C# rövid kódrészletei a csharp-interactive nyelvi címkével megadhatnak egy C# kódrészletet, amely a böngészőben fut. (A beágyazott kódrészletek a csharp-interactive címkét használják, a forrásból származó kódrészletekhez használja a code-csharp-interactive címkét.) Ezek a kódrészletek egy kódablakot és egy kimeneti ablakot jelenítenek meg a cikkben. A kimeneti ablak megjeleníti az interaktív kód végrehajtásának kimenetét, miután a felhasználó futtatta a kódrészletet.

A C# interaktív felülete megváltoztatja a kódrészletek használatát. A látogatók futtathatják a kódrészletet az eredmények megtekintéséhez. Számos tényező segít meghatározni, hogy a kódrészletnek vagy a megfelelő szövegnek tartalmaznia kell-e a kimenettel kapcsolatos információkat.

Mikor jelenítse meg a várt kimenetet a kódrészlet futtatása nélkül?

• A kezdőknek szóló cikkekben érdemes megadni a kimenetet, hogy az olvasók összehasonlíthassák a munkájuk kimenetét az elvárható válasszal.
• Azokat a kódrészleteket, amelyekben a kimenet a témakör szerves része, meg kell jelenítenie ezt a kimenetet. A formázott szövegről szóló cikkeknek például a kódrészlet futtatása nélkül kell megjelenítenie a szövegformátumot.
• Ha a kódrészlet és a várt kimenet is rövid, fontolja meg a kimenet megjelenítését. Ezzel időt takaríthat meg.
• A kimenetnek az aktuális vagy az invariáns kulturális környezet általi befolyásolásáról szóló cikkekben érdemes magyarázatot fűzni a várható kimenethez. Az interaktív REPL (Read Evaluate Print Loop) Linux-alapú gazdagépen fut. Az alapértelmezett kulturális környezet és az invariáns kulturális környezet különböző operációs rendszereken és számítógépeken más-más kimenetet eredményez. A cikknek a Windows, Linux és Mac rendszeren várható kimenetet is ismertetnie kell.

Mikor kell kizárni a várt kimenetet a kódrészletből?

• Azokat a cikkeket, amelyeknél a kódrészlet nagyobb kimenetet hoz létre, nem szabad megjegyzésbe foglalni. A kód elhomályosítja a kódrészlet futtatása után.
• Olyan cikkek, amelyekben a kódrészlet egy témakört mutat be, de a kimenet nem szerves a megértéshez. Ilyen például egy LINQ-lekérdezést futtató kód, amely a lekérdezés szintaxisát ismerteti, majd a kimeneti gyűjtemény minden elemét megjeleníti.

Hozzájárulás nem angol nyelvű tartalomhoz

A gépi fordítású (machine translated, azaz MT) tartalomhoz jelenleg nem fogadunk el hozzájárulásokat. A gépi fordítású tartalmak minőségének javítása érdekében egy neurális MT-motorra váltottunk át. Elfogadjuk, sőt örömmel vesszük azonban a hozzájárulást az ember által fordított tartalmakhoz, melyeket felhasználunk a neurális gépi fordítási motor betanításánál. Így idővel az emberi fordítással készült tartalmakhoz beküldött hozzájárulások mind az emberi fordítás, mind a gépi fordítás minőségét javítani fogják. A gépi fordítású tartalmaknál egy nyilatkozat jelenik majd meg arról, hogy a témakör egyes részei gépi fordítással készültek, de a Szerkesztés gomb nem jelenik meg, mert a továbbiakban nem lehetséges szerkeszteni a szöveget.

Közreműködői licencszerződés

Lekéréses kérelme egyesítéséhez alá kell írnia a .NET Foundation közreműködői licencszerződését (CLA). Ez egyszeri követelmény a .NET Foundation projektjeihez. A Közreműködői licencszerződésről (CLA) a Wikipédia szócikke ír bővebben.

A szerződés: .NET Foundation közreműködői licencszerződés (CLA)

A szerződést nem kell előre aláírnia. Lekéréses kérelmét a szokásos módon klónozhatja, elágaztathatja és benyújthatja. A leküldéses kérelmet annak létrehozása után egy CLA-robot sorolja be. Ha a módosítás kis mértékű (például egy gépelési hiba javítása), akkor a lekéréses kérelem a cla-not-required címkével lesz ellátva. Más esetben a cla-required besorolást kapja. A CLA aláírása után jelenlegi és jövőbeli lekéréses kérelmei mindig a cla-signed címkével lesznek ellátva.