Bookstore Reposu ve Okuma Haritası: Kodu Nereden Alırım, Hangi Parça Hangi Seride?

Sürüm notu: Bu yazıdaki Git komutları Git 2.54 ile denenmiştir; çıktılar, gerçek repo ile aynı düzende kurulmuş küçük bir deneme reposundan alınmıştır.

Önce Tahmin Et: Yazının Kodunu Almak

TDD (Test-Driven Development; önce testi, sonra kodu yazarak ilerleme) serisinin dördüncü yazısını okuyorsun ve kodu kendi makinende çalıştırmak istiyorsun. Sitedeki serilerin ortak örnek uygulaması Bookstore'un (bir online kitapçı) reposunu klonladın; her yazının bir tag'i olduğunu biliyorsun. Yazdığın komut ve aldığın cevap:

git switch tdd/04

fatal: a branch is expected, got tag 'tdd/04'
hint: If you want to detach HEAD at the commit, try again with the --detach option.

Üç soru. Git neden itiraz ediyor? Önerisine uyup --detach ile geçtikten sonra bir değişiklik yapıp commit'lersen o commit nereye gider? Ve dördüncü yazının üçüncüye göre neyi değiştirdiğini en kısa yoldan nasıl görürsün?

Repo'nun Düzeni: main, Seri Branch'leri ve Tag'ler

Sitedeki bütün seriler aynı Bookstore üzerinde çalıştığı için kod da tek bir GitHub reposunda duruyor. Adresi:

https://github.com/mrtozn1923/bookstore

Repo, site sahibinin hesabında açılınca bu adreste olacak; bu yazının yayınlandığı gün henüz erişilebilir olmayabilir. Düzeni üç kurala dayanıyor:

• main: referans uygulama. Bu serinin ikinci yazısında anlatılan Catalog, Ordering ve Inventory çekirdeği, testleri ve Angular istemcisi.
• series/<seri-slug>: her seri için bir branch. Seri, referans uygulamadan başlayıp kendi konusunu bu branch'te ekliyor.
• <seri-slug>/NN: seri branch'indeki her yazı bir commit ve o commit'i işaretleyen bir tag. tdd/04, TDD serisinin dördüncü yazısı bittiğindeki kodun tam hâli.

Tag, Git'te belirli bir commit'e verilmiş sabit bir isim; branch gibi ilerlemez. Yazıyı okuduğun gün de bir yıl sonra da tdd/04 aynı kodu gösterir. Branch ise serinin en son hâlini gösterir; seriye yeni yazı eklendikçe ilerler. Kod içermeyen yazıların, bu serinin birinci ve üçüncü yazısı gibi, ayrı bir kod hâli yoktur.

Önce Tahmin Et'teki hatanın sebebi de bu ayrım. git switch branch'ler arasında geçmek için tasarlanmış; bir tag'e geçmek, hiçbir branch'e bağlı olmayan bir commit'e geçmek demek. Git'in belgesi bu durumu "detached HEAD" olarak anlatıyor ve --detach seçeneğini inceleme ve atılabilir denemeler için öneriyor. Komut seni korumak için açık bir onay istiyor.

Bir Yazının Kodunu Almak

Bütün repoyu klonlayıp istediğin tag'e geçmek en genel yol:

git clone https://github.com/mrtozn1923/bookstore.git
cd bookstore
git switch --detach tdd/04

HEAD is now at 849a754 tdd/04

Artık çalışma klasöründe dördüncü yazının sonundaki kod var. Çalıştırma adımları yazının içinde ve repo'nun kökündeki README'de; referans uygulamanınkiler bu serinin ikinci yazısında. Hangi tag'lerin olduğunu görmek için:

git tag --list "tdd/*"

Yalnız bir serinin geçmişini istiyorsan klonu o branch'le sınırlayabilirsin. --single-branch ile klonlanan repoda o branch'in commit'lerini gösteren tag'ler de gelir:

git clone --branch series/tdd --single-branch https://github.com/mrtozn1923/bookstore.git bookstore-tdd

Repoyu daha önce klonladıysan yeni yazıların tag'lerini almak için git fetch --tags yeterli. Seri branch'inin en son hâliyle çalışmak istersen git switch series/tdd yaz; tam klonda Git, uzak branch'ten aynı adla yerel bir branch oluşturur.

İki Yazı Arasındaki Farkı Görmek

Her yazı bir tag olduğu için "bu yazı neyi değiştirdi?" sorusunun cevabı bir diff:

git diff --stat tdd/03 tdd/04
git diff tdd/03 tdd/04 -- src/

İlki değişen dosyaların listesini ve satır sayılarını, ikincisi yalnız src/ altındaki değişikliklerin kendisini gösterir. Seri boyunca neyin değiştiğini görmek için seri branch'ini main'le karşılaştırabilirsin:

git log --oneline main..origin/series/tdd
git diff --stat main origin/series/tdd

main..origin/series/tdd, seri branch'inde olup main'de olmayan commit'leri listeler; her satır bir yazı. Aynı karşılaştırmayı GitHub'ın web arayüzündeki compare sayfasında iki tag seçerek de yapabilirsin. Bu düzenin bir yazar tarafı da var: her yazı yalnız kendi değişikliğini içerdiği için diff kısa ve okunabilir kalıyor, yazının anlattığı ile kodun değişen kısmı birebir örtüşüyor.

Kendi Denemelerini Ayrı Bir Branch'te Yapmak

Tag'e --detach ile geçip denemeye başlayabilirsin, ama orada yaptığın commit'ler hiçbir branch'e ait değil. Başka bir yere geçtiğinde Git uyarır:

Warning: you are leaving 1 commit behind, not connected to
any of your branches:

  b010824 my experiment

If you want to keep it by creating a new branch, this may be a good time
to do so with:

 git branch <new-branch-name> b010824

Bu commit bir süre sonra Git'in temizliğiyle kaybolabilir. Önce Tahmin Et'teki ikinci sorunun cevabı bu: commit hiçbir branch'e gitmez. Denemeyi kalıcı yapmak istiyorsan baştan kendi branch'ini aç:

git switch -c my/tdd-04-experiment tdd/04

my/ önekini kendi branch'lerini seri branch'lerinden ayırmak için kullanıyoruz; zorunlu değil, sadece listede karışmasın diye. İki yazının kodunu yan yana açık tutmak istersen git worktree ikinci bir çalışma klasörü verir:

git worktree add ../bookstore-tdd-03 tdd/03

Bu klasör de detached HEAD ile açılır ve aynı repoyu paylaşır; ikinci bir klon gerekmez. İşin bitince git worktree remove ../bookstore-tdd-03 ile kaldırırsın. Git komutlarının ayrıntısı Git & GitHub serisinde.

Okuma Haritası: Nereden Başlamalı?

Bookstore'u tanımak için bu serinin ilk iki yazısı yeterli. Sonrası neye ilgi duyduğuna göre değişiyor. Aşağıdaki yollar bir öneri; seriler birbirinden bağımsız okunabiliyor ve her yazı Bookstore'u ilk geçtiği yerde kısaca yeniden tanıtıyor.

Backend geliştirici

C# Temelleri ile başla, C# ile Nesne Yönelimli Programlama, LINQ (Language Integrated Query; sorguları C# içinde yazma) ve C# Asenkron Programlama ile devam et. Sonra Web API tarafı için ASP.NET Core Web API serisine, veri erişimi için Entity Framework Core serisine ve SQL Temelleri'ne geç. Test için Unit Test ve TDD, ardından Integration ve E2E (end-to-end; uygulamayı uçtan uca deneyen) Test. Güvenlik tarafında Web Güvenliği (OWASP Top 10), API Güvenliği (OWASP API Top 10), ASP.NET Core Güvenliği ve Authentication ve Authorization serileri aynı API üzerinde çalışıyor. Bookstore büyüdükçe Caching, Background Job'lar ve Scheduled Job'lar, Message Queue'larla Çalışmak ve .NET'te Logging gerekiyor.

Frontend geliştirici

HTML5 (HTML'in güncel standardı) ve Semantic HTML, ardından JavaScript Temel, Orta ve İleri ile TypeScript Temel, Orta ve İleri. bookstore-web'deki konuların temeli Angular serisinde; RxJS ve Angular'da State Yönetimi serileri sepet ve katalog state'ini derinleştiriyor, Frontend Testleri serisi aynı sayfaları test ediyor, Frontend Güvenliği serisi de tarayıcı tarafındaki açıkları ele alıyor.

Mimariye ilgi duyan

Mimariye Giriş, Bookstore'un neden monolith olarak başladığını ve hangi kalite hedeflerine göre büyüdüğünü anlatıyor. SOLID (beş temel nesne yönelimli tasarım prensibinin baş harfleri) ve Design Principles ile Data Modeling ve Normalizasyon'dan sonra Clean, Onion ve Hexagonal Architecture, Vertical Slice Architecture ve Domain-Driven Design geliyor. Module sınırları Modular Monolith'te, event'ler Messaging ve Event-Driven Architecture'da, sipariş tarafının ayrı okuma ve yazma modelleri CQRS (Command Query Responsibility Segregation; yazma ve okuma modellerini ayırma) ve Event Sourcing'de, servislere bölünme Microservices'te ele alınıyor. Distributed Systems Temelleri, System Design ve Architecture Decision'lar serileri bu kararların büyük ölçekteki hâlini ve nasıl kayda geçirildiğini gösteriyor.

Ekip lideri

SDLC (Software Development Life Cycle; yazılımın fikirden bakıma kadar geçtiği aşamalar), Agile Mindset, Scrum ve Kanban serilerinde Bookstore ekibi çalışıyor. Product Management'a Giriş ve Requirements Analysis, Kurumsal Sipariş özelliğinin nasıl ortaya çıktığını anlatıyor; Estimation ve Planning aynı işleri tahmin edip planlıyor. Kod tarafında Test Stratejisi, Code Review ve Coding Conventions ve Ekip Standartları serileri ekibin ortak kurallarını konuşuyor.

Bookstore'un Parçaları Hangi Seride?

Aynı haritayı parçalara göre okumak istersen:

Tabloda adı geçen seriler ya yayında ya da bu dönem yazılıyor; yayındakilerin bir kısmı konuyu Bookstore'dan önce seçilmiş başka bir örnekle anlatıyor. "İlerideki" diye geçenler planlı ama henüz yazılmamış seriler; yayına girdiklerinde aynı repoda kendi branch'leriyle yer alacaklar.

Repoda Bugün Ne Var, Ne Yok?

Dürüst bir tablo: repo yeni ve bütün kod henüz içinde değil. main'deki referans uygulama hazır. Bu dönemden itibaren yazılan seriler kodlarını yazı yazı, doğrudan kendi branch'lerine ekliyor. Daha önce yayımlanmış serilerin kodu ise aşamalı olarak ekleniyor; o yazılarda örnek kod şimdilik yazının içinde duruyor ve bir kısmı repo'daki düzene göre değil, kendi içinde çalışacak kısa programlar olarak yazılmış.

Eski yazıların bir kısmında Bookstore yerine başka bir örnek de görebilirsin, en sık İK Portalı. Karşılıkları bu serinin ilk yazısında: şirket, departman ve çalışan Bookstore'da Institution, InstitutionUnit ve InstitutionUser; izin ya da satın alma onayı PurchaseApproval. Bir serinin branch'inin olup olmadığını görmenin en kısa yolu repoyu klonlayıp git branch -r ile uzak branch'leri listelemek.

Sık Düşülen Tuzaklar

Tag'e geçip orada çalışmaya devam etmek. Detached HEAD'deki commit'ler hiçbir branch'e ait değil; işini kaybetmemek için denemeye başlamadan git switch -c ile kendi branch'ini aç.

Seri branch'inin en son hâlini yazının kodu sanmak. series/tdd serinin son yazısını gösterir; dördüncü yazıyı okuyorsan tdd/04'e geçmelisin, yoksa henüz anlatılmamış kodu görürsün.

Seri branch'lerini birbirine merge etmeye çalışmak. Her seri main'den kendi yönünde ayrılıyor; iki serinin değişiklikleri birlikte çalışmak üzere tasarlanmadı. İki serideki fikri birleştirmek istiyorsan kendi branch'inde, elle ve bilerek yap.

Repoyu klonlayıp hemen dotnet run yazmak. Referans uygulama bir SQL Server ve connection string bekliyor; adımlar README'de ve bu serinin ikinci yazısında. Connection string'i repo'daki appsettings.json'a değil user-secrets'a yaz, yoksa ilk commit'inle şifren de gider.

Repo'nun bugün eksik olan kısımlarını hata sanmak. Yayındaki eski bir serinin branch'i yoksa bu, kodun henüz taşınmadığı anlamına geliyor; yazının içindeki kod çalışmaya devam ediyor.

Küçük Bir Deneme

★☆☆ Repo açıldığında klonla ve git branch -r ile seri branch'lerini, git tag --list ile tag'leri listele. Kaç seri branch'i var, en çok tag'i olan hangisi?

★★☆ Bir serinin art arda iki tag'ini seç ve git diff --stat ile değişen dosyalara bak. Sonra o yazıyı okuyup yazıda anlatılan değişikliklerle diff'i karşılaştır: diff'te olup yazıda geçmeyen bir dosya var mı?

★★★ Okuma haritasından kendine bir yol seç ve my/ önekli bir branch açıp yol boyunca yaptığın denemeleri orada biriktir. Her seri bittiğinde main'le karşılaştırıp kendi değişikliklerinin özetini bir paragrafla yaz.

Bu seri burada bitiyor: Bookstore'un ürün tarafını, teknik yapısını ve kodunun nerede durduğunu gördük. Bundan sonra hangi seriyi okursan oku, karşına çıkan Book, Order ya da StockItem bu üç yazıda tanıdığın uygulamanın parçası; bir şey belirsiz kaldığında dönüp bakacağın yer bu seri.