Berkontribusi pada repositori dokumentasi .NET

Artikel
08/10/2023

Terima kasih atas minat Anda untuk berkontribusi pada dokumentasi .NET!

Dokumen ini mencakup proses untuk berkontribusi pada artikel dan sampel kode yang dihosting di situs dokumentasi .NET. Kontribusi mungkin sesingkat koreksi kesalahan ketik atau serumit artikel baru.

Situs dokumentasi .NET dibangun dari beberapa repositori. Ini hanya beberapa dari mereka:

Panduan untuk kontribusi

Kami menghargai kontribusi komunitas terhadap dokumentasi. Daftar berikut ini memperlihatkan beberapa aturan panduan yang perlu diingat saat Anda berkontribusi pada dokumentasi .NET:

Jangan mengejutkan kami dengan permintaan pull besar. Sebagai gantinya, ajukan masalah dan mulai diskusi sehingga kami dapat menyetujui arah sebelum Anda menginvestasikan banyak waktu.
JANGAN sertakan kode sampel sebaris dalam artikel.
DO menggunakan proyek cuplikan dengan kode untuk disematkan dalam artikel.
IKUTI petunjuk dan panduan suara dan nada ini.
DO menggunakan file templat sebagai titik awal pekerjaan Anda.
BUAT cabang terpisah di fork Anda sebelum mengerjakan artikel.
DO mengikuti alur GitHub.
BLOG DO dan tweet (atau apa pun) tentang kontribusi Anda jika Anda mau!

Mengikuti panduan ini akan memastikan pengalaman yang lebih baik bagi Anda dan bagi kami.

Proses kontribusi

Langkah 1: Jika Anda tertarik untuk menulis konten baru atau merevisi konten yang ada secara menyeluruh, buka masalah yang menjelaskan apa yang ingin Anda lakukan. Konten di dalam folder dokumen diatur ke dalam bagian yang tercermin dalam daftar isi (TOC). Tentukan di mana topik akan berada di TOC. Dapatkan umpan balik tentang proposal Anda.

-atau-

Pilih masalah yang ada dan atasi. Anda dapat melihat daftar masalah terbuka dan sukarelawan kami untuk mengerjakan yang Anda minati:

Filter berdasarkan label masalah pertama yang baik untuk, baik, masalah pertama yang baik.
Filter menurut label up-for-grabs untuk masalah yang sesuai dengan kontribusi komunitas. Masalah ini biasanya memerlukan konteks minimal.
Kontributor berpengalaman dapat mengatasi masalah yang menarik.

Saat Anda menemukan masalah untuk dikerjakan, tambahkan komentar untuk menanyakan apakah masalah tersebut terbuka.

Setelah Anda memilih tugas untuk dikerjakan, buat akun GitHub dan lanjutkan ke Langkah 2.

Langkah 2: Fork /dotnet/docs repositori (atau repositori mana pun yang Anda kontribusikan) sesuai kebutuhan dan buat cabang untuk perubahan Anda.

Untuk perubahan kecil, lihat Mengedit di browser.

Langkah 3: Buat perubahan pada cabang baru ini.

Jika ini adalah topik baru, Anda dapat menggunakan file templat ini sebagai titik awal Anda. Ini berisi panduan penulisan dan juga menjelaskan metadata yang diperlukan untuk setiap artikel, seperti informasi penulis. Untuk informasi selengkapnya tentang sintaks Markdown yang digunakan dalam konten Microsoft Learn, lihat Referensi markdown.

Navigasikan ke folder yang sesuai dengan lokasi TOC yang ditentukan untuk artikel Anda di Langkah 1. Folder tersebut berisi file Markdown untuk semua artikel di bagian tersebut. Jika perlu, buat folder baru untuk menempatkan file untuk konten Anda. Artikel utama untuk bagian tersebut disebut index.md.

Untuk gambar dan sumber daya statis lainnya, buat subfolder yang disebut media di dalam folder yang berisi artikel Anda, jika belum ada. Di dalam folder media, buat subfolder dengan nama artikel (kecuali untuk file indeks). Untuk informasi selengkapnya tentang tempat menempatkan file Anda, lihat bagian Contoh struktur folder.

Jangan sertakan kode sebaris dalam artikel, kecuali Anda menunjukkan konstruksi yang tidak dikompilasi. Sebagai gantinya, gunakan proyek cuplikan kode dan sertakan kode menggunakan ekstensi kode. Itu memastikan bahwa kode sampel Anda divalidasi oleh sistem CI kami.

Untuk cuplikan kode, buat subfolder yang disebut cuplikan di dalam folder yang berisi artikel Anda, jika belum ada. Di dalam folder cuplikan, buat subfolder dengan nama artikel. Dalam kebanyakan kasus, Anda akan memiliki cuplikan kode untuk ketiga bahasa .NET utama, C#, F#, dan Visual Basic. Dalam hal ini, buat subfolder bernama csharp, fsharp, dan vb untuk masing-masing dari tiga proyek. Jika Anda membuat cuplikan untuk artikel di bawah folder docs/csharp, docs/fsharp, atau docs/visual-basic , cuplikan hanya akan berada dalam satu bahasa sehingga Anda dapat menghilangkan subfolder bahasa. Untuk informasi selengkapnya tentang tempat menempatkan file Anda, lihat bagian Contoh struktur folder.

Cuplikan kode adalah contoh kode kecil dan terfokus yang menunjukkan konsep yang dibahas dalam artikel. Program yang lebih besar yang ditujukan untuk unduhan dan eksplorasi harus terletak di repositori dotnet/sampel . Sampel lengkap tercakup dalam bagian tentang Berkontribusi pada sampel.

Langkah 4: Kirim permintaan pull (PR) dari cabang Anda ke cabang default.

Penting

Fungsionalitas otomatisasi komentar tidak tersedia di salah satu repositori dokumen .NET saat ini. Anggota tim dokumen .NET akan meninjau dan menggabungkan PR Anda.

Setiap PR biasanya harus mengatasi satu masalah pada satu waktu, kecuali beberapa masalah terkait dengan perbaikan PR yang sama. PR dapat mengubah satu atau beberapa file. Jika Anda mengatasi beberapa perbaikan pada file yang berbeda, PR terpisah lebih disukai.

Jika PR Anda memperbaiki masalah yang ada, tambahkan Fixes #Issue_Number kata kunci ke deskripsi PR. Dengan begitu, masalah ditutup secara otomatis ketika PR digabungkan. Untuk informasi selengkapnya, lihat Menautkan permintaan pull ke masalah menggunakan kata kunci.

Tim .NET akan meninjau PR Anda dan memberi tahu Anda jika ada pembaruan/perubahan lain yang diperlukan untuk menyetujuinya.

Langkah 5: Buat pembaruan yang diperlukan untuk cabang Anda seperti yang dibahas dengan tim.

Pertahan akan menggabungkan PR Anda ke cabang default setelah umpan balik diterapkan dan perubahan Anda disetujui.

Kami secara teratur mendorong semua penerapan dari cabang default ke cabang langsung dan kemudian Anda akan dapat melihat kontribusi Anda secara langsung dalam dokumentasi .NET. Kami biasanya menerbitkan setiap hari selama minggu kerja.

Contoh struktur folder

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

Catatan

Folder bahasa di bawah cuplikan tidak diperlukan di area panduan bahasa, di mana hanya satu bahasa yang diasumsikan. Misalnya, dalam panduan C#, diasumsikan bahwa semua cuplikan adalah C#.

Struktur yang ditunjukkan di atas mencakup satu gambar, portability_report.png, dan tiga proyek kode yang menyertakan cuplikan kode yang disertakan dalam artikel porting-overview.md .

Cuplikan /folder bersama digunakan untuk cuplikan yang dapat mencakup beberapa artikel dalam folder induk yang sama, seperti folder porting dalam contoh sebelumnya. Hanya gunakan folder bersama saat Anda memiliki alasan khusus untuk melakukannya, seperti kode XAML yang dirujuk oleh beberapa artikel, namun tidak dapat dikompilasi di folder khusus artikel.

Media juga dapat dibagikan di seluruh artikel ketika artikel tersebut berada di folder induk yang sama, seperti folder porting dalam contoh sebelumnya. Folder bersama ini harus dihindari jika memungkinkan, dan hanya digunakan ketika masuk akal. Misalnya, mungkin masuk akal untuk berbagi layar pemuatan umum untuk aplikasi yang ditunjukkan, atau berbagi dialog Visual Studio yang digunakan kembali di beberapa artikel.

Penting

Untuk alasan historis, banyak cuplikan yang disertakan disimpan di bawah folder /samples di repositori dotnet/docs . Jika Anda membuat perubahan besar pada artikel, cuplikan tersebut harus dipindahkan ke struktur baru. Namun, jangan khawatir tentang memindahkan cuplikan untuk perubahan kecil.

Berkontribusi pada sampel

Kami membuat perbedaan berikut untuk kode yang mendukung konten kami:

Sampel: pembaca dapat mengunduh dan menjalankan sampel. Semua sampel harus berupa aplikasi atau pustaka lengkap. Di mana sampel membuat pustaka, sampel harus menyertakan pengujian unit atau aplikasi yang memungkinkan pembaca menjalankan kode. Mereka sering menggunakan lebih dari satu teknologi, fitur, atau toolkit. File readme.md untuk setiap sampel akan merujuk ke artikel sehingga Anda dapat membaca lebih lanjut tentang konsep yang tercakup dalam setiap sampel.
Cuplikan: mengilustrasikan konsep atau tugas yang lebih kecil. Mereka mengkompilasi tetapi tidak dimaksudkan untuk menjadi aplikasi lengkap. Mereka harus berjalan dengan benar, tetapi bukan contoh aplikasi untuk skenario umum. Sebaliknya, mereka dirancang sekecil mungkin untuk menggambarkan satu konsep atau fitur. Ini seharusnya tidak lebih dari satu layar kode.

Sampel disimpan di repositori dotnet/sampel . Kami berupaya menuju model di mana struktur folder sampel kami cocok dengan struktur folder dokumen kami. Standar yang kita ikuti adalah:

Folder tingkat atas cocok dengan folder tingkat atas di repositori dokumen . Misalnya, repositori dokumen memiliki folder pembelajaran mesin/tutorial , dan sampel untuk tutorial pembelajaran mesin ada di folder samples/machine-learning/tutorials .

Selain itu, semua sampel di bawah folder inti dan standar harus dibangun dan dijalankan di semua platform yang didukung oleh .NET Core. Sistem build CI kami akan memberlakukan itu. Folder kerangka kerja tingkat atas berisi sampel yang hanya dibuat dan divalidasi di Windows.

Proyek sampel harus dibangun dan dijalankan pada sekumpulan platform terluas yang mungkin untuk sampel yang diberikan. Dalam praktiknya, itu berarti membangun aplikasi konsol berbasis .NET Core jika memungkinkan. Sampel yang khusus untuk web atau kerangka kerja UI harus menambahkan alat tersebut sesuai kebutuhan. Contohnya termasuk aplikasi web, aplikasi seluler, aplikasi WPF atau WinForms, dan sebagainya.

Kami berupaya untuk memiliki sistem CI untuk semua kode. Saat Anda membuat pembaruan apa pun untuk sampel, pastikan setiap pembaruan adalah bagian dari proyek yang dapat dibangun. Idealnya, tambahkan pengujian untuk kebenaran pada sampel juga.

Setiap sampel lengkap yang Anda buat harus berisi file readme.md . File ini harus berisi deskripsi singkat sampel (satu atau dua paragraf). readme.md Anda harus memberi tahu pembaca apa yang akan mereka pelajari dengan menjelajahi sampel ini. File readme.md juga harus berisi tautan ke dokumen langsung di situs dokumentasi .NET. Untuk menentukan di mana file tertentu di peta repositori ke situs tersebut, ganti /docs di jalur repositori dengan https://learn.microsoft.com/dotnet.

Topik Anda juga akan berisi tautan ke sampel. Tautkan langsung ke folder sampel di GitHub.

Menulis sampel baru

Sampel adalah program dan pustaka lengkap yang dimaksudkan untuk diunduh. Mereka mungkin kecil dalam cakupan, tetapi mereka menunjukkan konsep dengan cara yang memungkinkan orang untuk menjelajahi dan bereksperimen sendiri. Panduan untuk sampel memastikan pembaca dapat mengunduh dan menjelajahi. Periksa sampel Parallel LINQ (PLINQ) sebagai contoh dari setiap panduan.

Sampel Anda harus menjadi bagian dari proyek yang dapat dibangun. Jika memungkinkan, proyek harus dibangun di semua platform yang didukung oleh .NET Core. Pengecualian untuk ini adalah sampel yang menunjukkan fitur khusus platform atau alat khusus platform.
Sampel Anda harus sesuai dengan gaya pengkodan runtime untuk mempertahankan konsistensi.

Selain itu, kami lebih suka penggunaan static metode daripada metode instans saat menunjukkan sesuatu yang tidak memerlukan instans objek baru.
Sampel Anda harus menyertakan penanganan pengecualian yang sesuai. Ini harus menangani semua pengecualian yang kemungkinan akan dilemparkan dalam konteks sampel. Misalnya, sampel yang memanggil metode Console.ReadLine untuk mengambil input pengguna harus menggunakan penanganan pengecualian yang sesuai saat string input diteruskan sebagai argumen ke metode. Demikian pula, jika sampel Anda mengharapkan panggilan metode gagal, pengecualian yang dihasilkan harus ditangani. Selalu tangani pengecualian spesifik yang dilemparkan oleh metode , bukan pengecualian kelas dasar seperti Pengecualian atau SystemException.

Untuk membuat sampel:

Ajukan masalah atau tambahkan komentar ke komentar yang sudah ada yang sedang Anda kerjakan.
Tulis topik yang menjelaskan konsep yang ditunjukkan dalam sampel Anda (misalnya: docs/standard/linq/where-clause.md).
Tulis sampel Anda (contoh: WhereClause-Sample1.cs).

Buat Program.cs dengan Titik masuk utama yang memanggil sampel Anda. Jika sudah ada, tambahkan panggilan ke sampel Anda:

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

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

Anda membuat cuplikan .NET atau sampel apa pun menggunakan .NET CLI, yang dapat diinstal dengan .NET SDK. Untuk membangun dan menjalankan sampel Anda:

Buka folder sampel dan buat untuk memeriksa kesalahan:
```
dotnet build
```
Jalankan sampel Anda:
```
dotnet run
```
Tambahkan readme.md ke direktori akar sampel Anda.

Ini harus menyertakan deskripsi singkat tentang kode, dan merujuk orang ke artikel yang mereferensikan sampel. Bagian atas readme.md harus memiliki metadata yang diperlukan untuk browser sampel. Blok header harus berisi bidang berikut:
```
---
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
---
```
- Koleksi languages hanya boleh menyertakan bahasa yang tersedia untuk sampel Anda.
- Koleksi products harus mencakup hanya produk yang relevan dengan sampel Anda.

Kecuali jika dicatat, semua sampel dibangun dari baris perintah pada platform apa pun yang didukung oleh .NET. Ada beberapa sampel yang khusus untuk Visual Studio dan memerlukan Visual Studio 2017 atau yang lebih baru. Selain itu, beberapa sampel menunjukkan fitur khusus platform dan akan memerlukan platform tertentu. Sampel dan cuplikan lain memerlukan .NET Framework dan akan berjalan pada platform Windows, dan akan memerlukan Paket Pengembang untuk versi Kerangka Kerja target.

Pengalaman interaktif C#

Semua cuplikan yang disertakan dalam artikel menggunakan tag bahasa untuk menunjukkan bahasa sumber. Cuplikan kode pendek di C# dapat menggunakan csharp-interactive tag bahasa untuk menentukan cuplikan C# yang berjalan di browser. (Cuplikan kode sebaris menggunakan csharp-interactive tag, untuk cuplikan yang disertakan dari sumber, gunakan code-csharp-interactive tag.) Cuplikan kode ini menampilkan jendela kode dan jendela output dalam artikel. Jendela output menampilkan output apa pun dari menjalankan kode interaktif setelah pengguna menjalankan cuplikan.

Pengalaman interaktif C# mengubah cara kami bekerja dengan cuplikan. Pengunjung dapat menjalankan cuplikan untuk melihat hasilnya. Sejumlah faktor membantu menentukan apakah cuplikan atau teks terkait harus menyertakan informasi tentang output.

Kapan menampilkan output yang diharapkan tanpa menjalankan cuplikan

Artikel yang ditujukan untuk pemula harus memberikan output sehingga pembaca dapat membandingkan output pekerjaan mereka dengan jawaban yang diharapkan.
Cuplikan di mana output bersifat integral dengan topik harus menampilkan output tersebut. Misalnya, artikel tentang teks yang diformat harus menampilkan format teks tanpa menjalankan cuplikan.
Ketika cuplikan dan output yang diharapkan pendek, pertimbangkan untuk menampilkan output. Ini menghemat sedikit waktu.
Artikel yang menjelaskan bagaimana budaya saat ini atau budaya invarian memengaruhi output harus menjelaskan output yang diharapkan. REPL interaktif (Read Evaluate Print Loop) berjalan pada host berbasis Linux. Budaya default, dan budaya invarian menghasilkan output yang berbeda pada sistem operasi dan mesin yang berbeda. Artikel ini harus menjelaskan output di sistem Windows, Linux, dan Mac.

Kapan harus mengecualikan output yang diharapkan dari cuplikan

Artikel di mana cuplikan menghasilkan output yang lebih besar tidak boleh menyertakannya dalam komentar. Ini mengaburkan kode setelah cuplikan dijalankan.
Artikel di mana cuplikan menunjukkan topik, tetapi outputnya tidak terintegrasi untuk memahaminya. Misalnya, kode yang menjalankan kueri LINQ untuk menjelaskan sintaks kueri lalu menampilkan setiap item dalam koleksi output.

Catatan

Anda mungkin melihat bahwa beberapa topik saat ini tidak mengikuti semua panduan yang ditentukan di sini. Kami berupaya mencapai konsistensi di seluruh situs. Periksa daftar masalah terbuka yang saat ini kami lacak untuk tujuan tertentu tersebut.

Berkontribusi pada konten non-bahasa Inggris

Kontribusi untuk konten Terjemahan Mesin (MT) saat ini tidak diterima. Dalam upaya untuk meningkatkan kualitas konten MT, kami telah beralih ke mesin Neural MT. Kami menerima dan mendorong kontribusi untuk konten Human Translated (HT), yang digunakan untuk melatih mesin Neural MT. Jadi seiring waktu, kontribusi terhadap konten HT akan meningkatkan kualitas HT dan MT. Topik MT akan memiliki penafian yang menyatakan bahwa bagian dari topik mungkin MT, dan tombol Edit tidak akan ditampilkan, karena pengeditan dinonaktifkan.

Catatan

Sebagian besar dokumentasi yang dilokalkan tidak menawarkan kemampuan untuk mengedit atau memberikan umpan balik melalui GitHub. Untuk memberikan umpan balik tentang konten yang dilokalkan, gunakan https://aka.ms/provide-feedback formulir.

Perjanjian lisensi kontributor

Anda harus menandatangani Perjanjian Lisensi Kontribusi .NET Foundation (CLA) sebelum PR Anda digabungkan. Ini adalah persyaratan satu kali untuk proyek di .NET Foundation. Anda dapat membaca selengkapnya tentang Perjanjian Lisensi Kontribusi (CLA) di Wikipedia.

Perjanjian: Perjanjian Lisensi Kontributor Yayasan .NET (CLA)

Anda tidak perlu menandatangani perjanjian di muka. Anda dapat mengkloning, fork, dan mengirimkan PR Anda seperti biasa. Saat PR Anda dibuat, PR diklasifikasikan oleh bot CLA. Jika perubahannya kecil (misalnya, Anda memperbaiki kesalahan ketik), maka PR diberi label dengan cla-not-required. Jika tidak, itu diklasifikasikan sebagai cla-required. Setelah Anda menandatangani CLA, permintaan pull saat ini dan di masa mendatang diberi label sebagai cla-signed.

Berkontribusi pada repositori dokumentasi .NET

Panduan untuk kontribusi

Proses kontribusi

Contoh struktur folder

Berkontribusi pada sampel

Menulis sampel baru

Pengalaman interaktif C#

Kapan menampilkan output yang diharapkan tanpa menjalankan cuplikan

Kapan harus mengecualikan output yang diharapkan dari cuplikan

Berkontribusi pada konten non-bahasa Inggris

Perjanjian lisensi kontributor

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan: