6.1 GitHub - Bir Projeye Katkıda Bulunmak

Diyelim ki, Arduino programlanabilir mikrodenetleyicisinde çalıştırmak için kod arayan Tony https://github.com/schacon/blink adresinde harika bir program dosyası bulur.

Tek sorun, yanıp sönme hızının çok yüksek olması. Her ışıltı arasında 1 saniye yerine 3 saniye beklemenin çok daha iyi olduğunu düşünüyoruz. Bu yüzden programı iyileştirelim ve bir değişiklik önerisi olarak projeye geri gönderelim.

Öncelikle, kendi kopyamızını almak için yukarıda belirtildiği gibi Fork düğmesine tıklıyoruz. Kullanıcı adımız burada "tonychacon" olduğu için kendi kopyamızı https://github.com/tonychacon/blink adresinde bulabilir ve burada düzenleyebiliriz. Yerel olarak kopyalayacak, bir tema dalı oluşturacak, kod değişikliği yapacak ve son olarak bu değişikliği GitHub’a geri iteceğiz.

Şimdi GitHub’daki çatalımıza geri dönersek; GitHub’ın yeni tema dalını ittiğinizi fark ettiğini, değişikliklerimizi kontrol etmek ve orijinal projeye bir Birleştirme İsteği açmak için büyük yeşil bir düğme sunduğunu görebiliriz.

Alternatif olarak, <kullanıcı>/<proje>/dal (örnekte: tonychacon/blink/tema_dalı) adresindeki "Branches" (dallar) sayfasına giderek dalınızı bulabilir ve oradan yeni bir birleştirme isteği açabilirsiniz.

Yeşil düğmeye tıklarsak, birleştirme isteğimize bir başlık ve açıklama vermemizi isteyen bir ekran görürüz. Genellikle buna biraz çaba harcamak faydalı olur, çünkü iyi bir açıklama, orijinal projenin sahibinin ne yapmaya çalıştığınızı, önerdiğiniz değişikliklerin doğru olup olmadığını ve değişikliklerin kabul edilmesinin orijinal projeyi iyileştirip iyileştirmeyeceğini belirlemesine yardımcı olur.

Ayrıca, master dalından önde (ahead) olan tema dalımızdaki katkıların bir listesini (bu senaryoda sadece bir tane) ve bu dalın projenin sahibi tarafından birleştirilmesi durumunda yapılacak tüm değişikliklerin birleştirilmiş bir farkını görürüz.

Bu ekranda Create pull request (birleştirme isteği oluştur) düğmesine tıkladığınızda, çatalınızı aldığınız proje sahibi bir değişiklik önerildiği konusunda bir bildirim alacak ve tüm bu bilgilere bağlantı veren bir sayfaya yönlendirilecek.

Bu noktada, proje sahibi önerilen değişikliği inceleyebilir, birleştirebilir, reddedebilir veya üzerine yorum yapabilir. Diyelim ki fikri beğendi, ancak ışığın kapalı kalma süresinin, açık kalma süresinden biraz daha uzun sürmesini tercih etti.

Bu konuşma, GitHub üzerinde çevrimiçi olarak gerçekleşirken, Dağıtık Git bölümünde sunulan iş akışlarında e-posta üzerinden gerçekleşir. Proje sahibi, birleştirilmiş farkı gözden geçirebilir ve herhangi bir satıra tıklayarak bir yorum bırakabilir.

Yönetici bu yorumu yaptıktan sonra, isteği açan kişi (ve hatta repoyu izleyen herkes) bir bildirim alır. Bunu özelleştirmeyi daha sonra ele alacağız, ancak e-posta bildirimlerini açmış olsaydı, Tony şöyle bir e-posta alırdı:

Ayrıca herkes bu birleştirme isteği üzerine herkese açık yorumlar da yapabilir. Birleştirme isteği tartışma sayfası bölümünde, projenin sahibinin hem bir kod satırına yorum yapması, hem de tartışma bölümünde genel bir yorum bırakması örneğini görebilirsiniz. Kod yorumlarının da konuşmaya dahil edildiğini görebilirsiniz.

Şimdi katkılayıcı, değişikliklerinin kabul edilmesi için yapması gerekenleri görebilir. Neyse ki bu çok basittir. E-posta üzerinden serinizi tekrar oluşturup, posta listesine yeniden göndermeniz gerekirken; GitHub’ta sadece konu dalına tekrar katkı işleyip iterseniz, birleştirme isteği otomatik olarak güncellenir. Birleştirme isteği kapanışı bölümünde, güncellenen bir birleştirme isteğindeki eski kod yorumunun, artık değiştirilmiş bir satıra yapıldığı için daraltıldığını görebilirsiniz.

Varolan bir birleştirme talebine yeni katkılar işlemek, bir bildirim tetiklemez; bu yüzden Tony düzeltmelerini ittikten sonra, proje sahibine istenen değişikliği yaptığını bildirmek için bir yorum bırakmaya karar verir.

Bu birleştirme talebinin "Files Changed" (Değiştirilen Dosyalar) sekmesine tıklarsanız, "bileşke fark"ı alırsınız; yani, bu konu dalı birleştirildiğinde, ana dalınıza kaynaşacak olan tüm kod farkını. git diff terimi, temelde bu birleştirme isteğinin dayandığı dal için git diff master...<branch> komut çıktısını site otomatik olarak gösterir. Bu tür bir fark hakkında daha fazla bilgi için Katkıları Tanımlamak bölümüne bakın.

Diğer bir dikkat çekici nokta ise; GitHub’ın birleştirme isteğinin temiz bir şekilde birleştirilip birleştirilemeyeceğini kontrol etmesi ve birleştirmeyi sunucuda yapmak için bir düğme oluşturmasıdır. Bu düğme, repoya yazma erişiminiz varsa ve basit birleşme mümkünse görünür. Tıklarsanız, GitHub "ileri-sarma" (fast-forward) olabilecek durumlarda bile "ileri-sarmayan" (non-fast-forward) birleşmesi gerçekleştirir ve bir birleştirme katkısı oluşturur.

Tercih ederseniz, basitçe dalı çekip (pull), yerelde birleştirebilirsiniz (merge). Bu dalı master dala birleştirir ve GitHub’a iterseniz, birletşirme isteği otomatik olarak kapanır.

Bu, çoğu GitHub projesinin kullandığı temel iş akışıdır. Konu dalları oluşturulur, üzerlerinde birleştirme istekleri açılır, bir tartışma başlar, belki daha fazla çalışma yapılır ve sonunda istek ya kapatılır ya da birleştirilir.

Birçok projenin, birleştirme isteklerini; posta listesi tabanlı projelerin düşündüğü gibi sıralı ve kusursuz bir yama kuyruğu olarak görmediğini anlamak gereklidir. Çoğu GitHub projesi, Birleştirme isteği dallarını, önerilen bir değişiklik etrafında yapılan karşılıklı konuşmalar olarak düşünür ve uygulanan birleştirme bileşik bir fark ile sonuçlanır.

Değişiklik genellikle, kodun mükemmel olduğu düşünülmeden önce önerildiği için - ki posta listesi tabanlı yama serisi katkılarında bi çok daha nadirdir - bu önemli bir ayrımdır. Bu, yürütücülerle daha erken bir müzakere başlatır, böylece doğru çözüme varılması daha ziyade bir topluluk çabası haline gelir. Bir birleştirme isteğiyle kod önerildiğinde, yürütücüler veya topluluk bir değişiklik önerirse; yama serisi genellikle yeniden yapılmaz. Bunun yerine bu ek değişiklik, yeni bir katkı olarak dalın içine itilir ve önceki çalışmanın bağlamı korunur.

Örneğin, Birleştirme isteği kapanışı örneğine tekrar bakarsanız, katkı sağlayıcının katkısını yeniden temellemediğini (rebase) ve başka bir birleştirme isteği göndermediğini farkedeceksiniz. Bunun yerine, yeni katkılar işleyip, bunları mevcut dala itmiştir. Bu şekilde, gelecekte bu birleştirme isteğine tekrar baktığınızda, kararların neden alındığına dair tüm bağlamı kolayca görebilirsiniz. Sitedeki "Birleştir" düğmesine tıklamak; gerektiğinde orijinal tartışmayı aramayı kolaylaştırmak için, birleştirme isteğine referans veren bir birleştirme katkısı oluşturur.

Eğer birleştirme isteğiniz güncelliğini yitirirse veya başka bir nedenle temiz bir şekilde birleştirilemezse; yürütücünün bunu kolaylıkla birleştirebilmesi için bunu düzeltmek isteyeceksiniz. GitHub bunu sizin için test edecek ve her birleştirme isteğinin alt kısmında birleştirmenin normal olup olmadığını size bildirecektir.

Eğer Birleştirme isteği temizce yapılamaz gibi bir şey görürseniz; rengin yeşile dönmesi için dalınızı düzeltmek istersiniz, böylece yürütücü ekstra iş yapmak zorunda kalmaz.

Bunu yapmanın temel olarak iki yolu bulunmaktadır. Ya dalınızı hedeflediğiniz dalın (genellikle çatalladığınız reponun master dalı) üzerine yeniden temellersiniz (rebase) veya hedef dalı kendi dalınıza birleştirirsiniz.

GitHub’daki çoğu geliştirici, önceki bölümde ele aldığımız aynı nedenlerden dolayı, genellikle ikincisini seçer. Önemli olan katkı geçmişi ve nihai birleşmedir. Yeniden temellemek biraz daha temiz bir geçmiş sağlar ama çok daha zor ve hata yapmaya meyilli bir işlemdir.

Eğer hedeflediğiniz dala birleştirerek, birleştirme isteğinizi birleştirilebilir hale getirmek istiyorsanız; özgün repoyu yeni bir uzak repo olarak ekleyip, ordan getirirsiniz (fetch); ardından reponun ana dalını, kendi tema dalınıza birleştirirsiniz; sorunları düzeltir ve son olarak bunu üzerinde birleştirme isteği açtığınız dala geri itersiniz.

Önceki "tonychacon" örneğini kullanırsak; diyelim ki orijinal yazar birleştirme isteğinde çakışma oluşturacak bir değişiklik yaptı. Şimdi bu adımları birlikte gözden geçirelim.

Bunu yaptıktan sonra, birleştirme isteği otomatik olarak güncellenecek ve düzgünce birleştirilebiliyor mu diye tekrar kontrol edilecektir.

Git’in harika özelliklerinden biri de sürekli olarak bunu yapabilmenizdir. Çok uzun süreli bir projeniz varsa, hedef dal üzerinden defalarca birleştirme işlemi yapabilirsiniz ve sadece son birleştirdiğinizden beri ortaya çıkan çakışmalarla uğraşmanız gerekecektir; bu da süreci çok daha yönetilebilir hale getirir.

Eğer mutlaka dalı temizlemek için yeniden temellemek istiyorsanız, elbette yapabilirsiniz, ancak zaten açılmış olan dal üzerinde "zorla itme işlemi" (force push) yapmaktan kaçınmanız şiddetle tavsiye edilir. Başkaları tarafından çekilip, üzerinde daha fazla çalışma yapılmışsa; Yeniden Temellemenin Riskleri bölümünde belirtilen tüm sorunlarla karşılaşırsınız. Onun yerine, yeniden temellenmiş dalı GitHub’da yeni bir dala itin ve eskisine referans veren yepyeni bir birleştirme isteği açın, ardından orijinal isteği kapatın.

Sonraki sorunuz muhtemelen "Eski birleştirme isteğine nasıl referans verebilirim?" olabilir. GitHub’da yazı yazabileceğiniz hemen hemen her yerde diğer şeylere referans vermenin pek çok farklı yolu bulunmaktadır.

Başka bir birleştirme isteği veya bir iş paketine nasıl referans verileceğini açıklayalım. Tüm birleştirme istekleri ve iş paketleri numaralandırılır ve bunlar proje içinde benzersizdir. Örneğin, birleştirme isteği #3 ve iş paketi #3’e sahip olamazsınız. Başka bir birleştirme isteği veya iş paketine herhangi bir yerden referans vermek istiyorsanız, sadece herhangi bir yorum veya açıklamada #<num> yazabilirsiniz. Ayrıca, birleştirme isteği veya iş paketi başka bir yerdeyse daha kesin olabilirsiniz; kendi reponuzun bir çatalında bir paket veya isteğe atıfta bulunuyorsanız kullanıcıadı#<num> yazın, başka bir repoda bir şeye referans veriyorsanız kullanıcıadı/repo#<num> yazın.

Hadi bir örnek üzerinde görelim. Diyelimk ki önceki örnekteki dalı yeniden temelledik, onun için yeni bir birleştirme isteği oluşturduk ve şimdi yeni istekten eskisine referans vermek istiyoruz. Ayrıca, repo çatalındaki bir iş paketine ve tamamen farklı bir projedeki bir başka iş paketine de referans vermek istiyoruz. Açıklamayı Birleştirme İsteği çapraz referansları. örneğinde olduğu gibi doldurabiliriz.

Bu birleştirme isteği gönderildiğinde, bunların Birleştirme isteği çapraz referansları gibi işlendiğini göreceğiz. we’ll see all of that rendered like Birleştirme isteği çapraz referansları.

Orada belirttiğimiz tam GitHub URL’sinin yalnızca gerekli bilgilere kısaltıldığını görebilirsiniz.

Şimdi Tony, orijinal Birleştirme İsteğini kapatırsa: GitHub, birleştirme isteği zaman çizelgesinde otomatik olarak bir geri izleme etkinliği oluşturduğu için, yeni istekte onu görebiliriz. Bu, bu birleştirme isteğini ziyaret eden ve kapatıldığını gören herkesin, onu geçersiz kılan isteğe kolayca bağlantı kurabileceği anlamına gelir. Bu bağlantı Kapalı birleştirme isteği zaman çizelgesinde yeni birleştirme isteği bağlantısı. gibi görünecektir:

Sadece iş paketi numaralarını değil, aynı zamanda bir belirli bir katkıyı SHA-1 ile de referans verebilirsiniz. Tam 40 karakterlik bir SHA-1 belirtmeniz gerekiyor, ancak GitHub bu şekilde bir yorumda gördüğünde doğrudan katkıya bağlantı kurar. Tekrar edersek, katkıları çatallarda veya diğer repolarda, aynı iş paketlerinde olduğu gibi eferanslayabilirsiniz.

Özellikle Birleştirme İsteklerinde kullanım için, gerçekten kullanışlı ilk GitHub özel Markdown özelliği, Görev Listesidir. Bir görev listesi, yapmak istediğiniz işlerin tıklanabilir kutucuklar halinde listelenmesidir. Bunları bir İş Paketi veya Birleştirme İsteği içine koymak, genellikle tamamlanmasını isteğininiz işleri belirtir.

Bir görev listesini şöyle oluşturabilirsiniz:

Bunu, Birleştirme İsteği veya İş Paketinin açıklamasına dahil edersek, sonucu .Markdown yorumu içindeki görev listesi. gibi görüntülenir.

Bu genellikle Birleştirme İsteklerinde, Birleştirme İsteği’nin birleştirilmeye hazır olmadan önce, dalda ne yapmak istediğinizi belirtmek için kullanılır. Gerçekten harika olan kısım; doğrudan onay kutularına tıklayarak yorumları güncelleyebilmenizdir - görevleri işaretlemek için Markdown’ı doğrudan düzenlemenize gerek yoktur.

Dahası, GitHub, İşlerinizde ve Birleştirme İsteklerinizde görev listelerini arar ve onları listelenen sayfalarda meta veri olarak gösterir. Örneğin, içinde görevler listesi olan bir Birleştirme İsteğiniz varsa ve Birleştirme İstekleri giriş sayfasına bakarsanız, ne kadarının tamamlandığını görebilirsiniz. Bu, insanların Birleştirme İsteklerini alt görevlere ayırmalarına ve diğer kişilerin dalın gelişimini izlemesine yardımcı olur. Bunu Birleştirme İsteği listesinde görev listesi özeti. örneğinde görebilirsiniz.

Bu özellikler, bir Birleştirme İsteğini erken açarsanız ve yeni bir özelliğin gelişimini izlemek için kullanırsanız, son derece yararlı olabilir.

Yorumlara kod parçacıkları da ekleyebilirsiniz. Bu, deneyebileceğiniz bir şeyi gerçekten denemeden önce, bir katkı yorumu olarak eklemek isteğiğinizde, çok kullanışlı bir özelliktir. Ayrıca, çalışmayan veya bu Birleştirme İsteğinde uygulanabilecek kod örneği eklemek için de sıkça kullanılır.

Kod parçacığını eklemek için, onu (ters-kesme işaretleriyle "`") kafeslemelisiniz.

Eğer yukarıdaki örnekte olduğu gibi java ya da bir programlama dili adı eklerseniz, GitHub ek olarak kod parçacığının sözdizimini de vurgulamaya çalışacaktır. Yukarıdaki örnekte sonuç Kafeslenmiş kod örneği. gibi olur.

Eğer uzun bir yorumun küçük bir kısmına yanıt veriyorsanız, diğer yorumdan alıntı yapacağınız kısımları, > karakteriyle başlatarak seçebilirsiniz. Aslında, bu o kadar yaygın ve kullanışlıdır ki bunun için bir klavye kısayolu bile vardır. Yanıtlamak amacıyla alıntılamak istediğiniz metni vurgulayın ve r tuşuna basın, bu size yorum kutusunda bu metni alıntılayacaktır.

Alınıtı şöyle görünecektir:

İşlendikten sonra yorum İşlenmiş alıntı örneği.'deki gibi görünecektir.

Son olarak, yorumlarınızda emoji de kullanabilirsiniz. Bu aslında, birçok GitHub İşlemi ve Birleştirme İsteğinde gördüğünüz yorumlarda yaygın olarak kullanılır. Hatta GitHub’da bir emoji yardımcısı bile vardır. Bir yorum yazıyorsanız ve : karakteri ile başlarsanız, bir otomatik tamamlama, aradığınız emojiyi bulmanıza yardımcı olur.

Emojiler, yorumun herhangi bir yerinde :<isim>: şeklinde olabilir. Örneğin, şöyle bir şey yazabilirsiniz:

İşlendiğinde Yoğun emojili yorumlar. gibi görünür.

Bu yorum müthiş faydalı sayılmaz, ama duyguları başka türlü iletmenin zor olduğu bir ortama, eğlenceli bir unsur ekler.

Teknik olarak, bu GitHub’a özgün Markdown olmasa da son derece kullanışlıdır. Yorumlara Markdown görüntü bağlantıları eklemenin yanı sıra, ilgili URL’leri bulmak ve gömülü bağlantılar eklemek de zor olabilir; bu yüzden GitHub metin alanlarına sürükleyip bırakarak görüntüler gömmenize olanak tanır.

Görüntüleri yüklemek için sürükleyip bırakarak gömün. bağlantısına bakarsanız, metin alanının üstünde küçük bir ipucu, "Markdown olarak ayrıştırıldı" uyarısı, görebilirsiniz. Buna tıkladığınızda, GitHub’da Markdown ile yapabileceğiniz her şeyi içeren bir hatırlatma notuna erişebilirsiniz.