# 🤗 Transformers'a katkıda bulunun

## Katkı kuralları

PR açmanın iki yolu vardır: katkıya açık bir sorunu düzeltmek veya kendi kanıtını taşıyan bağımsız bir PR açmak. Yeni modeller de bağımsız bir PR ile eklenebilir, bkz. [Yeni bir model ekleme](#adding-a-new-model). Hugging Face personeli, bakımcılar ve bazı uzun süredir katkıda bulunanlar bu kurallardan muaftır.

**Bir sorunu düzeltme.** PR açıklamasında `Fixes #123` gibi bir kapatma anahtar kelimesiyle sorunu ilişkilendirin. Üzerinde çalışabileceğiniz konular:

- Bir bakıcının `triaged` etiketini eklediği, sizin açtığınız bir sorun
- [`contributions-welcome`](https://github.com/huggingface/transformers/labels/contributions-welcome) etiketli bir sorun
- [`New model`](https://github.com/huggingface/transformers/labels/New%20model) etiketli bir sorun, bkz. [Yeni bir model ekleme](#adding-a-new-model)

Diğer kişilerin sorunları, bir bakıcı aksi takdirde belirtmedikçe PR'lar için açık değildir. Çalışamayacağınız bir soruna bağlantı veren PR'lar kapatılacaktır.

Bir sorunun uygun koşulları sağladığını gördüğünüzde çalışmaya başlamadan önce izin almanıza gerek yoktur ve sorunları kişilere atamayız. "Bunun üzerinde çalışabilir miyim?" veya "Lütfen bunu bana atayın" gibi yorumlar sadece gürültü oluşturur, bu yüzden bunları atlayın ve PR'ınızı açın. Bir sorun için açılan ilk PR önceliklidir.

Bir `contributions-welcome` veya `New model` sorunu üzerinde çalışmadan önce, bunun için birinin zaten PR açıp açmadığını kontrol edin. Açıldıysa, başka bir PR açmayın. Hatalar fark ederseniz, önerilerinizi mevcut PR üzerinde bırakın. Yalnızca mevcut PR temelden hatalıysa veya eskiyse (yazarı, inceleme yorumlarına yanıt vermediyse veya iki haftadır değişiklik göndermediyse) rekabetçi bir PR açın. Bir yönetici incelemesi bekleyen bir PR eski sayılmaz. Her durumda, kendi PR'ınızı açmadan önce sorunda nedenini açıklayın.

**Bağımsız PR'ler.** Henüz kimse sorunu raporlamadıysa, bir issue olmadan PR açabilirsiniz. Bağımsız PR'ler, hata düzeltmesi, performans iyileştirmesi veya belgelerdeki bozuk bir örneğin düzeltilmesi gibi gerçek bir etkiye sahip kısa değişiklikler içindir. PR açıklaması, bir issue'da olduğu gibi aynı kanıtları içermelidir:

- bir hata için, `main` üzerinde başarısız olup düzeltmenizle geçen, yayımlanmış bir kontrol noktası, varsayılan bir yapılandırma veya belgelenmiş bir iş akışı kullanan kısa bir betik
- performans iyileştirmesi için, yayımlanmış bir checkpoint veya varsayılan yapılandırma gibi gerçekçi bir iş yükünde, çalıştırdığınız donanımda, önce ve sonra sayıları. Sıcak yolda olmayan bir fonksiyonun daha hızlı bir mikro-benchmark'ı sayılmaz.

Sorun için zaten bir issue varsa, PR'ınız bu issue üzerinden işlenir; issue'ı bağlayıp bağlamamanız fark etmez. Mevcut bir issue'ı çözen veya kanıt içermeyen bağımsız PR'lar kapatılır. Bu gereksinimler yeni modeller için geçerli değildir.

**Önce bir sorun (issue) açılması gereken değişiklikler.** Doğruluğu veya performansı etkilemeyen mekanik temizlikler ile belgelerde yazım hatalarına veya ifadelere yönelik toplu düzeltmeler, bir PR açılmadan önce bir sorun gerektirir. Değişikliği, nasıl yapılacağını ve kaç dosyayı etkilediğini önerin. Tek bir yazım hatası düzeltmesi, her iki yolda da bir PR için çok küçüktür.

**Diğer kişilerin PR'larını gözden geçirme.** Topluluk, bize yeni bir şey söylediğinde gelen yorumlara memnuniyetle bakılır, ancak yöneticiler bir PR'daki her yorumu okur ve kendi gözden geçirme araçlarımızı zaten çalıştırırız. Açmadığınız bir PR'a yorum yapmadan önce, söyleyecek belirli bir şeyiniz olduğundan emin olun:

- Bir sorun bulduysanız veya somut bir değişiklik önermek istiyorsanız, ilgili satırlara, ideal olarak yazarın doğrudan uygulayabileceği bir GitHub önerisi olarak, satır içi bir yorum bırakın. Bir hata bildiriyorsanız, bir yeniden üretici (reproducer) yardımcı olur.
- Eğer PR'inin düzelttiği sorunu siz raporladıysanız, durumunuzun düzeltilip düzeltilmediğine dair kısa bir not gerçekten çok faydalıdır.
- Lütfen genel özetler veya "bunu test ettim ve çalışıyor" raporları paylaşmayın. Bakıcı olmayan kişilerden gelen onaylar, bir PR'nin birleştirilip birleştirilmeyeceğini etkilemez ve PR'ı yeniden ifade eden uzun bir yorum, sonucu değiştirmeden bize zaman kaybettirir.

Kodunuzu nasıl yazacağınız size kalmıştır, ancak gönderdiğiniz her şeyden siz sorumlusunuz ve düşük kaliteli sorun veya PR'lar açan hesapları engelleme hakkımız saklıdır. Lütfen [davranış kurallarımızı](https://github.com/huggingface/transformers/blob/main/CODE_OF_CONDUCT.md) da saygıyla karşılayın.

 Sorunlarda ve PR'lerde aradığımız şeyler

- Hataların net teşhisi. Hızlı geçici çözümler genellikle kod şişkinliğine veya diğer modellerle uyumsuzluklara yol açar. Bir sorunun tam nedenini, özellikle
sorunun ilk olarak görüldüğü commit'i bulmak (örneğin [git bisect](https://git-scm.com/docs/git-bisect) ile) değerlidir.
- Diff'i en aza indirin. Gereksiz değişiklikleri ortadan kaldırmak için PR'ınızı kontrol edin. Test betikleri commit etmediğinizden emin olun
veya alakasız dosyalar. Yorumları yalnızca gerçekten gerekli olduklarında ekleyin. PR'ınız tek satırlık bir düzeltme olabilirse, tek satırlık bir düzeltme yapın. Bu, PR'ın incelenmesini çok daha kolay hale getirir ve kabul edilme olasılığını artırır.
- Sorunu yeniden üretmek için zaman ayırın. Bir kullanıcı bir sorun bildirdiğinde, sorunun asıl nedeni çoğu zaman
makinelerinde ortam sorunları yaşarlar ya da sorunu yanlış teşhis eder ve geçersiz bir çözüm önerirler. Raporu fazla ciddiye almak, bazen var olmayan sorunlar için bile kötü çözümlere yol açar. Sorunu gerçekten gördüğünüzden emin olmak için basit bir yeniden üretme betiği yazıp çalıştırmak değerlidir.
- Diğer modellerle karşılaştırın. Transformers deposu çok büyük ve birçok model benzer işler yapıyor. Ne zaman
Bir hatayı düzeltirken, hatanın diğer modellerde de olup olmadığını görmek değerlidir. PR'ınız, ilgili koda bir bağlantıyla birlikte “(diğer model) ile aynı yaklaşımı kullanarak düzeltildi” diyorsa, bu, düzeltmenin büyük olasılıkla doğru olduğunu ve kod tabanının geri kalanıyla uyumlu olduğunu bize söylediği için bakımcılar için çok faydalıdır.
- “Boş iş” PR'lerinden kaçının. Küçük stil değişiklikleri veya yorumlardaki yazım hatalarının düzeltilmesi için zamanımız yok ve kabul etmiyoruz
Kod analizi tarafından tespit edilen, ancak pratikte nadiren (hatta hiç) sorunlara yol açmayan "teorik hatalar" için düzeltmeler, bunlar bir saldırgan tarafından istismar edilemedikçe.
- Testleri yerel olarak ve CI'da doğrulayın. PR açmadan önce `make fix-repo` komutunu çalıştırın ve `utils/tests_fetcher.py` dosyasını kullanın
PR dalınızda değiştirdiğiniz dosyaları kapsayan testlerin listesini görüntüleyin. Bu testleri yerel olarak çalıştırın ve PR açmadan önce geçtiklerinden emin olun. PR'ınızı açtıktan sonra, lütfen CI'ın yeşil olduğunu doğrulayın ve herhangi bir kişiyi inceleme için bilgilendirmeden önce tüm sorunları giderin! Bu, bildirim spamini büyük ölçüde azaltır ve sürdürücülerin aklını başında tutar.

## Kurulum

1. GitHub'daki **Fork** düğmesini kullanarak [Transformers](https://github.com/huggingface/transformers) projesinin bir kopyasını hesabınıza alın ve ardından yerel olarak klonlayın.

  ```bash
  git clone git@github.com:<your Github handle>/transformers.git
  cd transformers
  ```

2. `upstream` adıyla Transformers deposunu bir uzak (remote) olarak ekleyin. `origin` sizin fork'unuza, `upstream` ise doğruluk kaynağına (source of truth) işaret eder. Bu sayede `origin`'e göndermeden ve bir PR açmadan önce yerel `main` dalınızı senkronize edebilirsiniz.

  ```bash
  git remote add upstream https://github.com/huggingface/transformers.git
  git remote -v
  # origin    git@github.com:<your Github handle>/transformers.git (fetch)
  # origin    git@github.com:<your Github handle>/transformers.git (push)
  # upstream  https://github.com/huggingface/transformers.git (fetch)
  # upstream  https://github.com/huggingface/transformers.git (push)
  ```

3. Fork'unuzu güncel tutun ve üzerinde çalışmak için bir dal başlatın. Ayrıca fork'unuzu GitHub arayüzünden **Sync fork** düğmesiyle senkronize edebilirsiniz.

  ```bash
  git checkout main && git pull upstream main && git push origin main
  git switch -c a-descriptive-name-for-my-branch
  ```

4. Kütüphaneyi düzenlenebilir modda yükleyin. Çoğu katkı için `[dev]` kullanın çünkü stil ve kalite denetimleri için gereken geliştirme araçlarını içerir. Model katkıları için `[torch,testing]` kullanın veya tam geliştirme bağımlılık setine gerek duyulmayan yalnızca doküman değişiklikleri ve küçük düzeltmeler için `[quality]` kullanın.

  ```bash
  pip install -e ".[dev]"

  # for model contributions
  pip install -e ".[torch,testing]"

  # for docs-only changes and small fixes
  pip install -e ".[quality]"
  ```

### Windows

Windows'ta [WSL](https://learn.microsoft.com/en-us/windows/wsl/) kullanmıyorsanız, git'i `CRLF` satır sonlarını `LF`'ye dönüştürmek üzere yapılandırın.

```bash
git config core.autocrlf input
```

Windows'ta `make` komutunu çalıştırmak için bir yol MSYS2 kullanmaktır.

1. [MSYS2'yi indirin](https://www.msys2.org/) (kurulumun `C:\msys64` dizinine yapıldığını varsayıyoruz).
2. Komut satırını `C:\msys64\msys2.exe` olarak açın (**Başlat** menüsünden erişilebilir olmalıdır).
3. Kabukta çalıştırın: `pacman -Syu` ve `make` paketini `pacman -S make` ile yükleyin.
4. PATH ortam değişkeninize `C:\msys64\usr\bin` ekleyin.

Artık `make` komutunu herhangi bir terminalden (PowerShell, cmd.exe vb.) kullanabilirsiniz.

## Sorunlar açma

Sorun [şablonlarını](https://github.com/huggingface/transformers/tree/main/.github/ISSUE_TEMPLATE) kullanın ve sorunun daha önce rapor edilmediğinden emin olun (GitHub'da Issues altında arama çubuğunu kullanın). Bir hata raporu, kendi kodunuzdaki değil Transformers'taki bir hatayla ilgili olmalı ve gerçek kullanım ile gerçek checkpoint'leri etkilemelidir; kodu okuyarak bulunan ve tetiklenmesi için çok standart dışı bir yapılandırma gerektiren "teorik bir hata", güvenlik sorunu olmadıkça triyaj edilmeyecektir. Hatanın en son sürümde veya `main` üzerinde yeniden üretildiğini gösteren kısa, kendi kendine yeten bir betik ekleyin; bunu yayımlanmış bir checkpoint veya varsayılan yapılandırma kullanarak yapın. Çalıştırılabilir bir yeniden üretici içermeyen hata raporları triyaj edilmeyecektir.

Hatanın kodunuzda mı yoksa kütüphanede mi olduğunu bilmiyorsanız, önce [forumda](https://discuss.huggingface.co/) veya [Discord](https://discord.com/invite/hugging-face-879548962464493619)’da sorun. Bu, GitHub’ın ele alınabilir kütüphane sorunlarına odaklanmasını sağlar.

## Yeni bir model ekleme

Transformers'a bir model eklemek, herkesin bu modeli yükleyip ince ayar yapmasını veya çıkarım (inference) çalıştırmasını mümkün kılar. Uygulamaya başlamadan önce, mimariniz ile Transformers'ta zaten bulunan ve güncel en iyi (state-of-the-art) modeller arasındaki farkları belirleyin. Bu farkları, inceleyicilerin (reviewer) modelin getirdiği zorlukları, mevcut kalıpların hangi kısımlarının yeniden kullanılabilir olduğunu ve modeller arasında standartlaştırılması gereken unsurları hızla anlayabilmesi için issue veya PR'da açıklayın.

Aşağıdaki kılavuzları izleyin.

1. [Modüler Transformers ile bir model ekleyin](https://github.com/huggingface/transformers/blob/main/docs/source/en/modular_transformers.md) — modeli modüler dosya kullanarak uygulayın ve bağımsız modelleme dosyalarını oluşturun.
2. [Docstring'leri otomatik oluştur](https://github.com/huggingface/transformers/blob/main/docs/source/en/auto_docstring.md) — boilerplate olmadan tutarlı docstring'ler oluşturmak için `@auto_docstring` dekoratörünü kullanın.
3. [Test](https://github.com/huggingface/transformers/blob/main/docs/source/en/testing.md) — doğruluğu doğrulamak ve katkıyı sürdürülebilir tutmak için model testleri yazın ve çalıştırın. Neden-sonuç dil modelleri için mümkün olduğunca neden-sonuç LM testcisinden devralın. Gerçek kontrol noktalarına karşı tam işlemci, belirteçleyici ve model yolunu doğruladıkları için entegrasyon testlerine öncelik verin.
4. [Model yapı kuralları](https://github.com/huggingface/transformers/blob/main/docs/source/en/modeling_rules.md) — `make typing` tarafından uygulanan statik model yapı kurallarına dosyalarınızın uyup uymadığını kontrol edin.

Bazı model eklemeleri ek entegrasyon gerektirir.

- Modeliniz görüntü veya video girdileri gerektiriyorsa [görüntü işleme bileşenlerini ekleyin](https://github.com/huggingface/transformers/blob/main/docs/source/en/add_vision_processing_components.md).
- Yayınlanan kontrol noktası parametre adları Transformers uygulamasıyla eşleşmediğinde [dinamik ağırlık yükleme](https://github.com/huggingface/transformers/blob/main/docs/source/en/weightconverter.md).

### Model ekleme zaman çizelgesi

Bir mimari için model katkıda bulunan kişiye ve topluluk talebine bağlı olarak model eklemeleri için dört zaman çizelgesi vardır.

- Day-0 entegrasyonu: Modeli, yeni bir sürüm yayınıyla birlikte Transformers'ta yayın gününde kullanılabilir hale getirin. En önemli çekirdek özelliklerin (kuantizasyon, FlashAttention, KV-cache vb.) desteklenmesine yardımcı oluyoruz, erken taslakları inceliyor ve zaman çizelgesine bağlı olarak model uygulamasını da üstlenebiliyoruz.

  Özellikle yeni mimariler için birkaç hafta öncesinden transformers@huggingface.co adresine e-posta gönderin. Kontrol noktanız ve yayınınız hazır olana kadar sizinle özel bir çatallama üzerinde birlikte çalışacağız.

- Aynı hafta entegrasyonu: Yüksek talep gören modeller, yazar iletşime geçmese bile genellikle bir hafta içinde eklenir.

  Bir tane talep etmek için [yeni model şablonu](https://github.com/huggingface/transformers/issues/new?assignees=&labels=New+model&projects=&template=new-model-addition.yml) ile bir sorun (issue) açın. Daha fazla aktiviteye sahip olan sorunlar kuyrukta daha hızlı ilerler.

- Yayın sonrası entegrasyon: Güçlü bir talebi olmayan veya üzerinde çalışacak kapasitemizin bulunmadığı modeller, upstream yayınından sonra eklenir.

  Harici katkıda bulunanlar, bir sorun açsın ya da açmasın, yeni bir model için doğrudan bir PR açabilir. Başlamadan önce, kimsenin zaten eklemeye çalışmadığından emin olmak için açık ["New model"](https://github.com/huggingface/transformers/issues?q=is%3Aopen+is%3Aissue+label%3A%22New+model%22) sorunlarını ve açık PR'ları kontrol edin. İnceleyip size rehberlik edeceğiz.

- Hub öncelikli sürüm: Modelinizi, upstream PR gerektirmeden, Transformers'ın [remote-code](https://github.com/huggingface/transformers/blob/main/docs/source/en/models.md#custom-models) desteği aracılığıyla doğrudan Hub üzerinde yayınlayın.

  Popüler Hub-first modeller genellikle daha sonra Transformers'a entegre edilir; bu da birinci sınıf dokümantasyon, bakım ve optimizasyonun kapısını açar. Hub-first, bir model eklemenin en düşük sürtünmeli yoludur. Ancak, bir modelin ağırlık dönüşümü veya diğer geriye dönük uyumluluk sorunları gerektirmesi durumunda daha kırılgan olabilir.

## Belgeler

Kaynak dosyalardan üretilen API referansı için, uygun olduğunda [`@auto_docstring`](https://github.com/huggingface/transformers/blob/main/docs/source/en/auto_docstring.md) dekoratörünü kullanın. Belgeleri düzenleme ve kullandığımız sözdizimi hakkında daha fazla ayrıntı için belgelerin [README](https://github.com/huggingface/transformers/blob/main/docs/README.md) dosyasına bakın.

