GitHub README nasıl yazılır? Başlangıç şablonu ve kontrol

Bir depoyu açan kişi kodu okumadan önce projenin ne yaptığını anlamak ister. README bu ilk açıklamadır. Uzun bir reklam metni yerine çalışan bir kurulum yolu, küçük bir örnek ve bilinen sınırlar yazmak daha yararlıdır.

Önce neyi çözmek istediğini belirle

Bir yabancının proje klasörünü açıp ne yapacağını anlayabildiği kısa bir README hazırlayacağız. İyi dokümantasyon, uygulamanın gerçek davranışıyla tutarlı olur.

Adım adım uygula

1 Amacı bir paragrafta yaz. Projenin kime hangi işi kolaylaştırdığını açıkla. Henüz olmayan özellikleri varmış gibi anlatma; ekran görüntüsü varsa gerçek sonuçtan al.
2 Tek bir çalıştırma yolu ver. Gereksinimleri, dosyaların nereye konacağını ve hangi komutun çalışacağını sırala. Temiz klasörde bu adımları kendin izle.
3 Sınırları belirt. Verinin nerede saklandığını, hangi özelliklerin yerel olduğunu ve hangi harici servislere gerek duyulduğunu yaz. Lisans ve katkı bilgisini ayrı tut.

Küçük bir örnek

Markdown

# Mini Bütçe
Gelir ve gider toplamını hesaplayan başlangıç projesi.

## Çalıştırma
Python kurulu bir terminalde: `python butce.py`

## Sınırlar
Veriler dosyaya kaydedilmez; örnek girdiler kodun içindedir.

Sık takılınan nokta

Yalnızca “npm install” yazmak, Node sürümünü veya sonraki çalıştırma adımını bilmeyen ziyaretçiye yetmeyebilir. Bir kez yapılandırdığın bilgisayarında eksik adımlar görünmeyebilir; boş bir klasörle kontrol et.

Şimdi kendin dene

Mevcut küçük projene README.md ekle. Bir arkadaşına yalnızca bu dosyayı okuyarak nasıl açacağını sor; takıldığı ifadeyi daha somut bir adımla değiştir.

Bir sonraki adım GitHub deposu oluşturma ve paylaşma rehberi →

Git İş Akışında En Sık Kullanılan Komutlar ve Görev Tablosu

GitHub README nasıl yazılır? Başlangıç şablonu ve kontrol konusunu uygularken hangi komutun dosyayı hangi aşamaya taşıdığını bilmek, yanlışlıkla kod kaybetmeni önler:

Komut	Ne Yapar?	Ne Zaman Kullanılır?	Dikkat Edilecek Nokta
`git status`	Değişen, eklenen ve izlenmeyen dosyaları listeler	Her işlemden önce ve sonra durumu görmek için	Hiçbir dosyayı değiştirmez, tamamen güvenlidir
`git diff`	Kaydedilmemiş satır farklarını gösterir	Commit atmadan önce "Ben neyi değiştirdim?" demek için	Unutulan `console.log` veya test satırlarını yakalar
`git add <dosya>`	Seçilen dosyayı hazırlık alanına (Staging) alır	Yalnızca ilgili değişikliği pakete dahil etmek için	`git add .` yapmadan önce `.gitignore` dosyasını kontrol et
`git commit -m "mesaj"`	Hazırlık alanındaki dosyaların kalıcı anlık görüntüsünü alır	Anlamlı bir küçük adım tamamlandığında	Mesajda "ne ve neden değişti" kısaca açıklanmalıdır
`git switch -c <dal-adi>`	Yeni bir çalışma dalı (branch) oluşturup oraya geçer	Yeni bir özellik veya hata düzeltmesine başlarken	Ana dalı (`main`) her zaman çalışır durumda tutar

Git ve GitHub Kullanırken 4 Altın Kural

1. Gizli Anahtarları ve `.env` Dosyasını Asla Commit Etme: Veritabanı şifrelerini ve API anahtarlarını ilk commit'ten önce `.gitignore` dosyasına ekle.
2. Dev Klasörleri (`node_modules`, `venv`, `bin/obj`) Depoya Gönderme: Bağımlılık klasörleri yerine yalnızca `package.json` veya `requirements.txt` dosyasını depoda tut.
3. Küçük ve Anlamlı Commit'ler At: 20 farklı dosyayı tek bir "güncelleme" mesajıyla kaydetmek yerine her özelliği ayrı commit olarak kaydet.
4. Paylaşılan Dalda `push --force` Kullanmaktan Kaçın: Ekip arkadaşlarının çalıştığı bir dalda geçmişi zorla ezmek diğer kişilerin çalışmalarını bozabilir.

Kopyalayıp Kullanabileceğin Profesyonel README.md Şablonu

Portfolyo projelerinde işe alım uzmanlarının ve diğer geliştiricilerin ilk baktığı yer README.md dosyasıdır. Aşağıdaki Markdown şablonunu kendi projenin kök dizinine ekleyip başlıkları projenle doldurabilirsin:

README.md

# 🚀 Proje Adı — Kısa ve Net Tek Cümlelik Açıklama

Bu proje, [hangi sorunu çözdüğünü 1-2 cümlede açıkla] amacıyla geliştirilmiştir.

## ✨ Özellikler
- Görev ekleme, filtreleme ve yerel depolamada (localStorage) saklama
- Mobil ve masaüstü uyumlu (Responsive) arayüz

## 🛠️ Kullanılan Teknolojiler
- HTML5, CSS3, JavaScript (ES6+)

## 💻 Yerelde Çalıştırma (Kurulum)
1. Depoyu bilgisayarınıza klonlayın: `git clone https://github.com/kullanici/proje.git`
2. Klasöre girin: `cd proje`
3. `index.html` dosyasını tarayıcıda açın veya `npm install && npm run dev` çalıştırın.

Sıkça Sorulan Sorular (SSS)

Yanlışlıkla `git add` yaptığım bir dosyayı nasıl geri çıkarırım? +

Dosyadaki kodlarını silmeden yalnızca hazırlık alanından (staging) çıkarmak için git restore --staged <dosya-adi> komutunu çalıştırabilirsin.

`git commit` yaptıktan sonra kodlarım otomatik olarak GitHub'a gider mi? +

Hayır. `git commit` değişikliği yalnızca senin bilgisayarındaki yerel `.git` veritabanına kaydeder. Uzak sunucuya (GitHub veya GitLab) göndermek için ayrıca git push komutunu çalıştırman gerekir.

Kaynak ve devamı

Resmi belgeleri aç ↗