Bagikan melalui

Git dan GitHub penting untuk dokumentasi Microsoft Learn

  • Artikel

Gambaran Umum

Sebagai kontributor dokumentasi Microsoft Learn, Anda akan berinteraksi dengan beberapa alat dan proses. Anda akan bekerja secara paralel dengan kontributor lain pada proyek yang sama, berpotensi konten yang sama persis, bahkan pada saat yang sama. Ini semua diaktifkan melalui perangkat lunak Git dan GitHub.

Git adalah sistem kontrol versi sumber terbuka. Ini memfasilitasi jenis kolaborasi proyek ini melalui kontrol versi terdistribusi file yang tinggal di repositori. Intinya, Git memungkinkan untuk mengintegrasikan aliran pekerjaan yang dilakukan oleh beberapa kontributor dari waktu ke waktu, untuk repositori tertentu.

GitHub adalah layanan hosting berbasis web untuk repositori Git, seperti yang digunakan untuk menyimpan konten Microsoft Learn . Untuk proyek apa pun, GitHub menghosting repositori utama, tempat kontributor dapat membuat salinan untuk pekerjaan mereka sendiri.

Artikel ini menentukan istilah kunci yang merupakan bagian dari alur kerja Microsoft Learn. Ini juga memberikan gambaran umum tentang repositori Git dan GitHub, dan menjelaskan bagaimana konten diatur untuk dokumentasi teknis Microsoft.

Cabang

Cabang memisahkan aliran pekerjaan (biasanya disebut sebagai versi). Kontribusi selalu dibuat dan dicakup ke cabang tertentu.

Mengisolasi perubahan terkait pada cabang tertentu memungkinkan Anda mengontrol dan memperkenalkan perubahan tersebut secara independen. Pada kenyataannya, tergantung pada jenis pekerjaan yang Anda lakukan, Anda dapat dengan mudah berakhir dengan beberapa cabang kerja di repositori Anda. Tidak jarang mengerjakan beberapa cabang secara bersamaan, masing-masing mewakili proyek yang berbeda.

Semua repositori berisi cabang default (biasanya bernama "utama") dan satu atau beberapa cabang yang sedang berlangsung (yang kami sebut cabang kerja) yang belum diintegrasikan ke dalam cabang default. Cabang default berfungsi sebagai versi saat ini dan "sumber kebenaran tunggal" untuk proyek. Ini adalah induk dari mana semua cabang lain di repositori dibuat.

Setiap kali Anda memperkenalkan serangkaian perubahan terkait logis baru, ini adalah praktik terbaik untuk membuat cabang kerja untuk mengelola perubahan Anda. Kami tidak menyarankan untuk membuat perubahan pada cabang default secara langsung.

Fork

Istilah ini biasanya digunakan sebagai kata benda ketika merujuk pada salinan repositori GitHub utama. Dalam praktiknya, fork hanyalah repositori lain. Tetapi itu khusus dalam arti bahwa GitHub mempertahankan koneksi kembali ke repositori utama/induk. Istilah ini terkadang digunakan sebagai kata kerja, seperti dalam "Anda harus mencabut repositori terlebih dahulu."

Git

Jika Anda terbiasa dengan sistem kontrol versi terpusat (seperti Team Foundation Server, SharePoint, atau Visual Source Brankas), Anda akan melihat bahwa Git memiliki alur kerja dan terminologi kontribusi unik untuk mendukung model terdistribusinya. Misalnya, tidak ada penguncian file yang biasanya terkait dengan operasi check-out/check-in. Sebaliknya, Git khawatir tentang perubahan pada tingkat yang lebih halus, membandingkan file byte byte.

Git juga menggunakan struktur berjenjang untuk menyimpan dan mengelola konten untuk proyek:

  • Repositori: Juga dikenal sebagai repositori, ini adalah unit penyimpanan tertinggi. Repositori berisi satu atau beberapa cabang.
  • Cabang: Unit penyimpanan yang berisi file dan folder yang membentuk kumpulan konten proyek. Untuk informasi selengkapnya tentang cabang, lihat bagian Cabang di artikel ini.

Kontributor berinteraksi dengan Git untuk memperbarui dan memanipulasi repositori di tingkat lokal dan GitHub:

  • Secara lokal melalui alat seperti konsol Git Bash, yang mendukung perintah Git untuk mengelola repositori lokal dan berkomunikasi dengan repositori GitHub.
  • Melalui www.github.com, yang mengintegrasikan Git untuk mengelola rekonsiliasi kontribusi yang mengalir kembali ke repositori utama.

GitHub

Catatan

Meskipun panduan dokumentasi didasarkan pada penggunaan GitHub, beberapa tim menggunakan Visual Studio Team Services untuk menghosting repositori Git. Klien Visual Studio Team Explorer menyediakan GUI untuk berinteraksi dengan repositori Team Services, sebagai alternatif untuk menggunakan perintah Git melalui baris perintah.
Selain itu, banyak pedoman berikut dikembangkan sebagai praktik terbaik dari pengalaman bertahun-tahun dalam menghosting konten layanan Azure di GitHub. Mereka mungkin diperlukan di beberapa repositori Microsoft Learn.

Semua alur kerja dimulai dan berakhir di tingkat GitHub, tempat repositori utama untuk proyek dokumentasi apa pun disimpan. Salinan yang dibuat kontributor untuk penggunaannya sendiri didistribusikan di beberapa komputer. Salinan ini akhirnya direkonsiliasi kembali ke repositori GitHub utama proyek.

Organisasi direktori

Cabang default proyek berfungsi sebagai versi konten saat ini untuk proyek. Konten di cabang default--dan cabang yang dibuat darinya--secara longgar selaras dengan organisasi artikel di halaman Microsoft Learn yang sesuai. Subdirektori digunakan untuk memisahkan seperti artikel (seperti layanan), konten media (seperti file gambar), dan file "sertakan" (yang memungkinkan penggunaan kembali konten).

Subdirektori artikel

Anda biasanya dapat menemukan direktori utama articles dari akar repositori. articles Direktori berisi sekumpulan artikel subdirektori dalam subdirektori diformat sebagai file Markdown yang menggunakan ekstensi .md. Beberapa repositori yang mendukung beberapa layanan menggunakan subdirektori generik /articles , seperti repositori Azure-Docs . Yang lain mungkin menggunakan nama khusus layanan, seperti repositori IntuneDocs , yang menggunakan /IntuneDocs.

Dalam akar direktori ini, Anda dapat menemukan artikel umum yang berkaitan dengan layanan atau produk secara keseluruhan. Dan biasanya, Anda kemudian dapat menemukan serangkaian subdirektori lain yang cocok dengan fitur/layanan atau skenario umum. Misalnya, artikel "komputer virtual" Azure ada di /virtual-machines subdirektori, dan artikel "pahami dan jelajahi" Intune ada di /understand-explore subdirektori.

Subdirektori media

Setiap direktori artikel berisi /media subdirektori untuk file media terkait. File media berisi gambar yang digunakan oleh artikel yang memiliki referensi gambar.

Menyertakan subdirektori

Setiap kali kami memiliki konten yang dapat digunakan kembali yang dibagikan di dua artikel atau lebih, konten tersebut ditempatkan di /includes subdirektori dari direktori utama articles . Dalam file Markdown yang menggunakan file include, ekstensi Markdown "include" yang sesuai ditempatkan di lokasi tempat file include perlu dirujuk.

Lihat Referensi markdown: Termasuk untuk panduan tambahan.

Templat file markdown

Untuk kenyamanan, direktori akar dari setiap repositori biasanya berisi file templat Markdown bernama template.md. Anda dapat menggunakan file templat ini sebagai "file pemula" jika Anda perlu membuat artikel baru untuk pengiriman ke repositori. File berisi:

  • Header metadata di bagian atas file, digambarkan oleh dua, 3 baris tanda hubung. Ini berisi berbagai tag yang digunakan untuk melacak informasi yang terkait dengan artikel. Metadata artikel memungkinkan fungsionalitas tertentu, seperti atribusi penulis, atribusi kontributor, remah roti, dan deskripsi artikel. Ini juga termasuk pengoptimalan SEO dan proses pelaporan yang digunakan Microsoft untuk mengevaluasi performa konten. Jadi metadata itu penting!
  • Bagian metadata yang menjelaskan berbagai tag dan nilai metadata. Jika Anda tidak yakin nilai yang akan digunakan untuk bagian metadata, Anda dapat membiarkannya kosong atau mengomentarinya dengan hashtag terkemuka (#), dan nilai tersebut akan ditinjau/diselesaikan oleh peninjau permintaan pull untuk repositori.
  • Berbagai contoh penggunaan Markdown untuk memformat elemen artikel.
  • Instruksi umum tentang penggunaan ekstensi Markdown, yang dapat Anda gunakan untuk berbagai jenis pemberitahuan.
  • Contoh penyematan video dengan menggunakan iframe.
  • Instruksi umum tentang penggunaan ekstensi dokumentasi teknis Microsoft, yang dapat Anda gunakan untuk kontrol khusus seperti tombol dan pemilih.

Asal

Istilah ini adalah nama yang ditetapkan ke koneksi antara repositori lokal Anda dan repositori tempatnya dikloning. Dalam alur kerja Microsoft Learn, asal mewakili koneksi ke fork Anda. Istilah ini kadang-kadang digunakan sebagai moniker untuk repositori asal itu sendiri, seperti dalam "Ingatlah untuk mendorong perubahan Anda ke asal."

Permintaan pull

Permintaan pull (PR) adalah permintaan bagi pemilik konten untuk menarik perubahan Anda ke sumber resmi. PR memungkinkan model kolaborasi GitHub dengan meminta perubahan (juga dikenal sebagai penerapan) dari cabang kerja Anda untuk ditarik dan digabungkan ke cabang lain. Dalam kebanyakan kasus, cabang lain adalah cabang default di repositori utama.

PR juga berfungsi sebagai mekanisme untuk memberikan umpan balik kepada kontributor dari proses validasi Microsoft Learn dan peninjau PR untuk menyelesaikan masalah atau pertanyaan sebelum perubahan digabungkan ke cabang default.

Jarak Jauh

Jarak jauh adalah koneksi bernama ke repositori jarak jauh, seperti jarak jauh "asal" atau "hulu". Git menyebut ini sebagai jarak jauh karena digunakan untuk mereferensikan repositori yang dihosting di komputer lain. Dalam alur kerja Microsoft Learn, remote selalu merupakan repositori GitHub.

Upstram

Seperti asal remote, upstream adalah koneksi bernama ke repositori lain. Dalam alur kerja Microsoft Learn, upstream mewakili koneksi antara repositori lokal Anda dan repositori utama tempat fork Anda dibuat. Istilah ini terkadang digunakan sebagai moniker untuk repositori hulu itu sendiri, seperti dalam "Ingatlah untuk menarik perubahan terbaru dari hulu."

Pelajari lebih lanjut

Jika Anda tidak terbiasa dengan Git atau GitHub, sumber daya ini dapat membantu Anda belajar, menjadi produktif, atau menjawab pertanyaan.

Sumber daya kontrol sumber Git

Sumber daya GitHub

  • GitHub Halo Dunia latihan mulai cepat: Tutorial online yang mengekspos Anda ke dasar-dasar Git menggunakan GitHub.
  • Panduan GitHub: Rumah dokumentasi GitHub.
  • Sumber daya pembelajaran GitHub: Sumber daya GitHub lain yang berguna.
  • Glosarium: Glosarium istilah Git dan GitHub yang berguna.
  • Paket pengembang siswa GitHub: Akses gratis ke alat pengembang terbaik untuk siswa.

Tanya Jawab Umum

Apa itu Git?

Git membantu melacak perubahan ketika banyak orang bekerja pada kode komputer bersama-sama. Ini seperti mesin waktu untuk kode, sehingga Anda dapat melihat apa yang berubah dan kembali jika diperlukan.

Mengapa menggunakan Git?

Ini bagus untuk kerja tim. Git memudahkan banyak orang untuk mengerjakan proyek yang sama tanpa mengacaukan pekerjaan satu sama lain. Ini juga membantu memperbaiki kesalahan dengan mudah.

Bagaimana cara kerja Git?

Git menyimpan semua versi kode proyek. Saat Anda membuat perubahan, Git mengambil gambar (seperti rekam jepret) dari apa yang berbeda. Anda dapat membuat versi yang berbeda secara bersamaan tanpa masalah.

Apa itu cabang di Git?

Cabang seperti jalur yang berbeda dalam proyek. Mereka membiarkan orang mengerjakan hal-hal baru tanpa mengubah proyek utama. Nantinya, mereka dapat membawa perubahan ini kembali ke proyek utama.

Apa itu penerapan di Git?

Penerapan seperti titik penyimpanan. Ini adalah cara untuk merekam perubahan yang Anda buat. Setiap penerapan memiliki ID unik dan catatan tentang apa yang diubah.

Apa itu GitHub?

GitHub adalah situs web tempat Anda dapat menyimpan proyek Git Anda. Ini seperti hub besar untuk berbagi dan bekerja sama pada kode dengan orang lain. Ini juga membantu dalam melacak siapa yang mengubah apa.

Apa perbedaan GitHub dengan Git?

Git adalah alat untuk melacak perubahan, sementara GitHub adalah tempat untuk menyimpan proyek Anda dan bekerja sama. GitHub menggunakan Git untuk melakukan sihirnya.

Apakah GitHub gratis?

Ya, untuk proyek yang dapat dilihat semua orang. Tetapi untuk proyek privat (hanya Anda dan tim Anda), Anda mungkin perlu membayar. Mereka menawarkan paket yang berbeda dengan fitur tambahan.

Apa itu permintaan pull di GitHub?

Permintaan pull seperti meminta untuk menempatkan perubahan Anda ke dalam proyek utama. Orang dapat meninjau dan mendiskusikan perubahan sebelum ditambahkan.

Seberapa aman GitHub?

GitHub mengurus keamanan dengan baik. Mereka menggunakan kode dan aturan khusus untuk memastikan hanya orang yang tepat yang dapat mengakses dan mengubah kode Anda. Anda juga dapat menambahkan lapisan keamanan tambahan seperti autentikasi dua faktor untuk keamanan yang lebih baik.