Docs belgeleri için Git ve GitHub temel özellikleri

Genel Bakış

Docs içeriğine katkıda bulunan bir kullanıcı olarak birden fazla araç ve işlem ile etkileşimde bulunursunuz. Aynı projede diğer katkıda bulunanlarla paralel olarak, muhtemelen tam olarak aynı içerik üzerinde ve hatta aynı zamanda çalışırsınız. Tüm bunlar, Git ve GitHub yazılımları ile sağlanır.

Git, açık kaynaklı bir sürüm denetim sistemidir. Depolarda bulunan dosyaların dağıtılmış sürüm denetimi yoluyla bu tip toplu proje işbirliğini kolaylaştırır. Temel olarak Git, herhangi bir depoda birden çok katkıda bulunan tarafından yapılan iş akışlarını tümleştirmeyi mümkün kılar.

GitHub, Git depoları için web tabanlı bir barındırma hizmetidir( örneğin, depo içeriği depolamak için docs.microsoft.com kullanılır. Herhangi bir proje için GitHub, ana depoyu barındırır ve katkıda bulunanlar, bu depodan kendi işlerinin kopyasını alabilirler.

Git

Merkezileştirilmiş sürüm denetim sistemlerine (Team Foundation Server, SharePoint veya Visual SourceSafe gibi) yabancı değilseniz kendi dağıtılmış modelini desteklemek için Git’in benzersiz bir katkı iş akışı ve terminolojisi olduğunu fark edebilirsiniz. Örneğin, normalde giriş/çıkış işlemleriyle birlikte gelen dosya kilitleme işlemi burada yoktur. Git, değişiklikleri daha ayrıntılı bir düzeyde ele alır ve dosyaları bayt düzeyinde karşılaştırır.

Git ayrıca, bir projenin içeriğini yönetmek için katmanlı bir yapı kullanır:

• Depo - Aynı zamanda repo olarak bilinir, en üst düzey depolama birimidir. Bir depo bir veya daha fazla dal içerir.
• Dal:Projenin içerik kümesinde yer alan dosya ve klasörleri içeren bir depolama birimi. Dallar, iş akışlarını (genellikle sürümler olarak adlandırılır) birbirinden ayırır. Katkılar her zaman belirli bir dal kapsamında yapılır. Tüm depolar varsayılan dal (genellikle "main" olarak adlandırılır) ve varsayılan dala geri birleştirilecek bir veya daha fazla dal içerir. Varsayılan dal, proje için geçerli sürüm ve "tek doğruluk kaynağı" olarak görev kullanır. Depodaki diğer tüm dallar bu üst öğeden oluşturulur.

Katkıda bulunanlar, yerel ve GitHub seviyelerinde depoları güncelleştirmek ve yönlendirmek için Git’i kullanır:

• Yerel depoları yönetmek ve GitHub depoları ile iletişime geçmek için Git komutlarını destekleyen Git Bash konsolu gibi araçlarla yerel olarak.
• Ana depoya geri akan katkıların birleşimini yönetmek için Git’i tümleştiren www.github.com aracılığıyla.

GitHub

Tüm iş akışları, herhangi bir Docs projesinin ana deposunun saklandığı GitHub seviyesinde başlayıp biter. Katkıda bulunanların kendi kullanımları için oluşturduğu kopyalar birden fazla bilgisayara dağıtılır. Bu kopyalar sonunda projenin ana GitHub deposuyla uzlaştırılır.

Dizin düzeni

Daha önce belirtildiği gibi, projenin varsayılan dalı projenin geçerli içerik sürümü olarak görev başındadır. Varsayılan dalda (ve dallarda oluşturulan) içerik, ilgili Docs sayfalarındaki makalelerin organizasyonuyla gevşek bir şekilde hizalanır. Alt dizinler; benzer içerikler (hizmetler gibi), medya içerikleri (görüntü dosyaları gibi) ve içeriğin tekrar kullanımını sağlayan “ekleme” dosyalarının ayrılması için kullanılır.

Bir ana articles dizinini genellikle deponun kökünde bulabilirsiniz. Makale dizini bir alt dizin kümesini içerir. Alt dizinlerdeki makaleler, .md uzantısı kullanan Markdown dosyaları olarak biçimlendirilir. Birden fazla hizmeti destekleyen bazı depolar, genel bir /articles alt dizini kullanır, örneğin /articles deposu. Diğerleri ise hizmete özgü bir ad kullanabilir, örneğin kullanan Intune-Docs deposu.

Bu dizinin kökünde, hizmet veya ürünün geneliyle alakalı makaleler bulabilirsiniz. Genelde özellikler/hizmetler veya yaygın senaryolarla eşleşen başka bir alt dizinler serisi bulabilirsiniz. Örneğin Azure “sanal makine” makaleleri /virtual-machines alt dizininde, “anlama ve keşfetme” makaleleri ise /understand-explore alt dizininde yer alır.

Medya alt dizini

Her makale dizini, karşılık gelen medya dosyaları için bir /media alt dizini içerir. Medya dosyaları, görüntü başvuruları bulunan makaleler tarafından kullanılan görüntüler içerir.

Eklemeler alt dizini

İki ya da daha fazla makale tarafından paylaşılan yeniden kullanılabilir içerik olduğunda, bu içerikler ana /includes dizininden alınan bir articles alt dizinine yerleştirilir. Ekleme dosyasını kullanan Markdown dosyasında, ekleme dosyasına başvurulması gereken konuma karşılık gelen bir “ekleme” Markdown uzantısı yerleştirilir.

Ek rehberlik için bkz. Markdown başvurusu: Içerir.

Markdown dosyası şablonu

Kolaylık sağlamak için her deponun kök dizini genellikle template.md adlı bir Markdown şablon dosyası içerir. Depoya göndermek üzere yeni bir makale oluşturmanız gerekirse "başlangıç dosyası" olarak bu şablonu kullanabilirsiniz. Bu dosya şunları içerir:

• Dosyanın üst kısmında iki adet 3 kısa çizgi ile gösterilen bir meta veri üst bilgisi. Makaleyle ilgili izleme bilgileri için kullanılan çeşitli etiketleri içerir. Makale meta verileri yazar alıntısı, katılımcı alıntısı, içerik haritaları ve makale açıklamaları gibi belirli işlevleri etkinleştirir. Ayrıca, SEO iyileştirmeleri ve Microsoft’un içerik performansını değerlendirmek için kullandığı raporlama işlemlerini içerir. Bu nedenle meta veriler önemlidir!
• Çeşitli meta veri etiketlerini ve değerlerini açıklayan bir meta veri bölümü. Meta veri bölümü için kullanılacak değerlerden emin değilseniz bölümü boş bırakabilirsiniz veya başına (#) diyez etiketi koyarak yorumlayabilirsiniz, bunlar daha sonra depo için çekme isteğini gözden geçiren tarafından incelenir/tamamlanır.
• Bir makalenin öğelerini biçimlendirmeye yönelik çeşitli Markdown kullanım örnekleri.
• Çeşitli uyarı türleri için kullanabileceğiniz, Markdown uzantılarının kullanılması ile ilgili genel talimatlar.
• iframe kullanarak video ekleme örnekleri.
• Düğme ve seçici gibi özel denetimler için kullanabileceğiniz, docs.microsoft.com uzantılarının kullanılması ile ilgili genel yönergeler.

Çekme istekleri

Bir çekme isteği, katkıda bulunan kişinin varsayılan dala uygulanacak bir grup değişikliği sunması için kolay bir yol sağlar. Bu değişiklikler (işlemeler olarak da bilinir), katkıda bulunan kişinin dalında depolanır ve GitHub varsayılan dalda birleştirme etkisinin modelini oluşturabilir. Çekme isteği ayrıca katkıda bulunan kişiye, çekme isteğini gözden geçiren kişi tarafından yapılan derleme/doğrulama işleminden sonra geri bildirim yollamaya yarar. Böylece katkıda bulunan, değişiklikler varsayılan dalla birleştirilmeden önce olası sorunlar veya soruları çözebilir.

Önermek istediğiniz değişikliklerin boyutuna bağlı olarak çekme isteği ile katkıda bulunmanın iki yolu vardır. Bunu daha sonra, bu kılavuzun GitHub iş akışı bölümünde ayrıntılı şekilde açıklayacağız.