Membuat perubahan besar pada dokumentasi Microsoft Learn

Penting

Semua repositori yang diterbitkan ke Microsoft Learn telah mengadopsi Kode Etik Sumber Terbuka Microsoft atau Kode Etik .NET Foundation. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Kode Etik. Atau hubungi opencode@microsoft.com, atau conduct@dotnetfoundation.org dengan pertanyaan atau komentar apa pun.

Koreksi atau klarifikasi kecil terhadap contoh dokumentasi dan kode di repositori publik dicakup oleh Ketentuan Penggunaan learn.microsoft.com. Setiap perubahan akan menghasilkan komentar dalam permintaan pull, meminta Anda untuk mengirimkan Perjanjian Lisensi Kontribusi (CLA) online jika Anda bukan karyawan Microsoft. Anda harus mengisi formulir online sebelum permintaan pull Anda dapat digabungkan.

Artikel ini memperlihatkan kepada Anda cara mengubah artikel Microsoft Learn menggunakan alat lokal dan cocok untuk kontributor yang perlu membuat perubahan besar atau akan sering menjadi kontributor repositori. Kontributor yang sering biasanya memiliki perubahan yang sedang berlangsung atau berjalan lama yang melalui beberapa siklus build/validasi/penahapan atau rentang beberapa hari sebelum mereka menandatangani permintaan pull (PR) mereka.

Contoh jenis kontribusi ini meliputi:

• Membuat kontribusi besar. Misalnya, kontribusi Anda (penambahan, perubahan, atau penghapusan) mungkin mencakup beberapa artikel dan perlu diterapkan dan diuji sebagai satu unit pekerjaan dalam satu PR.
• Membuat dan menerbitkan artikel baru, yang biasanya memerlukan editor lokal yang lebih kuat.
• Menambahkan gambar baru atau memperbarui gambar, yang biasanya mengharuskan Anda membuat subdirektori baru media secara bersamaan, membuat file gambar, memperbarui tautan gambar dalam artikel, dan mempratinjau file Markdown di editor lokal untuk menguji penyajian gambar.
• Memperbarui artikel selama periode hari sebelum Anda menerbitkan. Dalam kasus ini, Anda biasanya perlu melakukan integrasi rutin perubahan lain yang terjadi di cabang default. Integrasi ini lebih mudah melalui Git Bash dan pengeditan lokal. Anda juga menjalankan risiko kehilangan pengeditan jika Anda melakukan ini melalui editor web GitHub dan menunggu sebelum Anda melakukan perubahan.
• Membuat pembaruan berkelanjutan ke artikel yang sama setelah PR dibuka. Meskipun Anda dapat menggunakan editor web GitHub untuk tujuan ini, Anda dapat membuat beberapa PR yang luar biasa untuk file yang sama, yang mungkin bertentangan satu sama lain.

Prasyarat

• Identifikasi repositori GitHub yang menyimpan dokumentasi yang ingin Anda edit.
• Buat akun GitHub, jika Anda tidak memilikinya.
• Instal alat Git dan Markdown.
• Siapkan repositori Git lokal.
• Tinjau dasar-dasar Git dan GitHub (opsional).

Membuat dan memeriksa cabang kerja Anda

Untuk memulai, buat cabang kerja baru di repositori lokal Anda untuk mengambil perubahan yang Anda usulkan. Untuk latar belakang lainnya tentang cabang, lihat dasar-dasar Git dan GitHub.

Tutorial ini menggunakan Git Bash dan Visual Studio Code, tetapi Anda dapat menggunakan klien dan editor Git apa pun yang Anda sukai.

1. Di Visual Studio Code, buka folder repositori kloning lokal Anda. Dari menu File , pilih Buka folder dan navigasikan ke folder di komputer Anda.

2. Pilih Lihat dari menu atas, lalu pilih Terminal untuk membuka terminal terintegrasi.

3. Di terminal terintegrasi, pastikan Anda berada di folder repositori.

4. Sebelum Anda membuat cabang kerja, pastikan cabang utama lokal Anda saat ini dengan segala sesuatu di cabang utama repositori produksi. Tugas ini memastikan cabang kerja Anda menangkap perubahan apa pun yang telah terjadi dalam repositori produksi sejak terakhir kali Anda menyinkronkannya.

   1. Beralih ke cabang utama di repositori lokal Anda:

      git checkout main 
      

   2. Pastikan cabang utama lokal Anda saat ini:

      git pull upstream main 
      

5. Buat cabang kerja lokal berdasarkan utama:

   git checkout -b <branch-name>
   

   <branch-name> adalah tempat penampung. Saat Anda menjalankan perintah, ganti dengan nama unik dan bermakna untuk cabang Anda dan hapus tanda kurung sudut.

6. Dorong cabang kerja lokal ke cabang jarak jauh di fork GitHub Anda:

   git push origin <branch-name> -u
   

   Opsi -u menautkan cabang lokal dan jarak jauh. Opsi ini memungkinkan Anda untuk mendorong penerapan ke fork Anda dengan memasukkan hanya git push alih-alih git push origin <branch-name>.

Menemukan file Markdown sumber

Untuk mengedit artikel, temukan file sumber untuk artikel di klon repositori lokal Anda. Dalam Visual Studio Code, akses file Markdown repositori melalui file explorer (ikon dokumen di bilah sisi kiri atas). Penjelajah file memperlihatkan struktur folder repositori, dan Anda dapat menavigasi ke file yang ingin Anda edit.

Jika Anda tidak dapat menemukan file, kunjungi artikel di Microsoft Learn dan pilih ikon Edit pensil. Lokasi folder relatif di repositori GitHub ditampilkan di URL. Berikut adalah contoh URL tautan Edit :

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

Berikut adalah contoh lokasi file untuk URL ini.

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

Mengedit file

1. Buka file di Visual Studio Code dengan memilihnya.
2. Buat perubahan Anda.
3. Simpan perubahan Anda dengan memilih Simpan File>. Gunakan Simpan Semua untuk menyimpan beberapa file sekaligus.

Menerapkan dan mendorong perubahan Anda

Jika Anda melakukan pengeditan substansial atau meninjau artikel untuk kesegaran, perbarui ms.date di blok metadata di bagian atas file. Format tanggal sebagai mm/dd/yyyy.

Anda dapat menggunakan terminal Visual Studio Code atau UI Visual Studio Code untuk menerapkan dan mendorong perubahan Anda.

Terminal Visual Studio Code

1. Jalankan git status perintah untuk memverifikasi bahwa hanya file yang Anda edit yang muncul dalam daftar file yang diubah.

   git status
   

2. Jalankan git add perintah diikuti dengan jalur file dan nama file untuk menahapkan file yang Anda ubah.

   git add folder-name/file-name.md
   

   Jika Anda mengubah beberapa file, masukkan git add perintah untuk setiap file.

   Atau, Anda dapat menjalankan git add . (perhatikan periode setelah add) untuk secara otomatis mentahapkan semua perubahan yang Anda buat. Metode ini lebih cepat tetapi dapat menyebabkan masalah dengan menyertakan perubahan yang Anda buat secara tidak sengaja.

3. Jalankan git status lagi untuk mengonfirmasi perubahan apa yang ditahapkan.

4. Jalankan git commit perintah diikuti dengan pesan penerapan untuk menyimpan perubahan di repositori kloning lokal Anda.

   git commit -m "your commit message"
   

5. Jalankan git push untuk mendorong perubahan Anda.

   git push
   

UI Visual Studio Code

Anda dapat membuat dan mendorong penerapan dengan menggunakan fitur integrasi Git visual Studio Code. Ingatlah untuk melanjutkan pekerjaan Anda pada komputer yang sama. Jika Anda beralih komputer, Anda tidak akan memiliki versi terbaru dari cabang kerja untuk dilanjutkan.

1. Pastikan repositori lokal Anda masih memiliki cabang kerja yang sama yang dicek keluar. Di UI Visual Studio Code, cabang ditampilkan di sudut kiri bawah. Nama cabang juga berfungsi sebagai tombol untuk beralih cabang.

   

2. Di bilah sisi kiri Visual Studio Code, pilih alat fork untuk melihat panel Kontrol Sumber: Git .

   

   File yang Anda edit muncul di bawah Perubahan dengan M di sebelah kanan untuk menunjukkan bahwa file telah dimodifikasi. File baru muncul dengan U (tidak terlacak), dan file yang dihapus muncul dengan D.

3. Tahap perubahan. Arahkan mouse ke atas baris Perubahan hingga + ikon muncul. Pilih ikon tersebut. Tindakan ini setara dengan git add perintah . File sekarang muncul di bagian Perubahan Bertahap.

4. Masukkan pesan penerapan seperti "perbarui tanggal metadata" di kotak teks Pesan , dan pilih tanda centang.

   

5. Dorong penerapan. Pilih tombol Sinkronkan perubahan yang muncul di bawah blok commit-message.

   

Anda telah melakukannya! Kode Anda sekarang ada di repositori GitHub Anda dan siap bagi Anda untuk membuka PR.

Perlu memperbaiki sesuatu yang Anda kirimkan? Mudah sekali! Cukup ulangi langkah-langkah di atas, dimulai dengan Edit file, untuk membuat perubahan di cabang yang sama dan kemudian menerapkan dan mendorong lagi (tidak perlu mengatur server upstream pada dorongan berikutnya dari cabang yang sama). Umumnya, cabang digunakan untuk memisahkan aliran pekerjaan, jadi Anda tidak perlu membuat cabang baru kecuali Anda siap untuk mengerjakan sesuatu yang lain.

Buat perubahan Anda berikutnya

Siap untuk membuat perubahan lain, tidak terkait dengan yang satu ini? Beralih kembali ke cabang default, tarik dari repositori upstream untuk memperbarui fork Anda, dan lihat cabang baru. Jalankan perintah berikut di Git Bash:

git checkout main
git pull upstream main
git checkout -b "branchname"
git push origin <branch-name> -u

Anda sekarang berada di cabang baru yang ditautkan ke cabang jarak jauh Anda, dan Anda siap untuk membuat lebih banyak perubahan. Anda sedang dalam perjalanan untuk menjadi kontributor ahli!

Langkah berikutnya

• Jika Anda telah menyelesaikan langkah-langkah di atas, sekarang saatnya untuk membuka PR untuk menggabungkan perubahan Anda ke cabang utama.
• Untuk mempelajari selengkapnya tentang topik seperti sintaks ekstensi Markdown dan Markdown, tinjau referensi Markdown.