Ultralytics Açık Kaynak Projelerine Katkıda Bulunma#

Hoş geldin! Ultralytics açık kaynak projelerimize katkıda bulunmayı düşündüğün için çok mutluyuz. Katılımın yalnızca depolarımızın kalitesini artırmaya yardımcı olmakla kalmaz, aynı zamanda tüm bilgisayarlı görü topluluğuna da fayda sağlar. Bu kılavuz, başlamana yardımcı olacak açık yönergeler ve en iyi uygulamaları sunar.

Davranış Kuralları#

Herkes için sıcak ve kapsayıcı bir ortam sağlamak amacıyla tüm katkıcıların Davranış Kurallarımıza uyması gerekir. Saygı, nezaket ve profesyonellik, topluluğumuzun temel değerleridir.

Çekme İstekleri Yoluyla Katkıda Bulunma#

Çekme istekleri (PR'ler) şeklindeki katkılarını büyük ölçüde takdir ediyoruz. İnceleme sürecini olabildiğince sorunsuz hâle getirmek için lütfen şu adımları izle:

1. Depoyu çatalla: İlgili Ultralytics deposunu (ör. ultralytics/ultralytics) GitHub hesabına çatallayarak başla.
2. Dal oluştur: Çatalladığın depoda, değişikliklerini açıkça yansıtan anlaşılır ve açıklayıcı bir ada sahip yeni bir dal oluştur (ör. fix-issue-123, add-feature-xyz).
3. Değişikliklerini yap: İyileştirmelerini veya düzeltmelerini uygula. Kodunun projenin stil yönergelerine uyduğundan ve yeni hata ya da uyarı oluşturmadığından emin ol.
4. Değişikliklerini test et: Göndermeden önce, beklediğin gibi çalıştıklarını ve gerilemelere neden olmadıklarını doğrulamak için değişikliklerini yerel olarak test et. Yeni işlev ekliyorsan testler ekle.
5. Değişikliklerini işle: Değişikliklerini kısa ve açıklayıcı işlem mesajlarıyla işle. Değişikliklerin belirli bir sorunu gideriyorsa sorun numarasını ekle (ör. Fix #123: Corrected calculation error.).
6. Çekme isteği oluştur: Dalından, özgün Ultralytics deposundaki main dalına bir çekme isteği gönder. Değişikliklerinin amacını ve kapsamını açıklayan net bir başlık ve ayrıntılı bir açıklama ekle.

Geliştirme Kurulumu#

Çatallamanı (veya ana deponu) klonla ve Python'ın yerel dosyalarını çalıştırıp yeniden yüklemeye gerek kalmadan her değişikliği alabilmesi için -e düzenlenebilir modda yükle:

git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .

Başka bir projenin PyPI paketi yerine bir çatallamaya bağımlı olmasını sağlamak için pip'i veya requirements.txt çatallamanın dalına yönlendir:

git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

Belgeleme Değişiklikleri#

Belge kaynakları docs/en/ altında bulunur. Bir PR açmadan önce depo kökünden geliştirme bağımlılıklarını yükle ve tam kapsamlı katı doğrulamayı çalıştır:

uv pip install -e ".[dev]"
python docs/build_docs.py

Doğrulama, zensical build --strict çalıştırılmadan önce oluşturulan başvuruları, makroları ve karşılaştırma sayfalarını hazırlar. Makro kullanmayan sayfaların daha hızlı canlı önizlemesi için zensical serve komutunu çalıştır.

Katkıda Bulunan Lisans Anlaşması İmzalama#

Çekme isteğini birleştirebilmemiz için Katkıda Bulunan Lisans Sözleşmemizi (CLA) imzalaman gerekir. Bu yasal sözleşme, katkılarının uygun şekilde lisanslanmasını ve projenin AGPL-3.0 lisansı kapsamında dağıtılmaya devam edebilmesini sağlar.

Çekme isteğini gönderdikten sonra CLA botu imzalama sürecinde sana yol gösterecektir. CLA'yı imzalamak için PR'ına şu ifadeyi belirten bir yorum eklemen yeterlidir:

I have read the CLA Document and I sign the CLA

Google Stili Belge Dizeleri#

Yeni işlevler veya sınıflar eklerken açık ve standartlaştırılmış belgeler için Google tarzı dokstring'ler ekle. Hem girdi hem de çıktı types değerlerini her zaman parantez içine al (ör. (bool), (np.ndarray)).

def example_function(arg1, arg2=4):
    """Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
        >>> example_function(1, 2)  # False
    """
    return arg1 == arg2

GitHub Actions CI Testleri#

Tüm çekme istekleri, birleştirilebilmeleri için GitHub Actions Sürekli Entegrasyon (CI) testlerinden geçmelidir. Bu testler, değişikliklerinin projenin kalite standartlarını karşıladığından emin olmak için lint denetimlerini, birim testlerini ve diğer kontrolleri içerir. CI çıktısını incele ve ortaya çıkan sorunları gider.

Kod Katkıları İçin En İyi Uygulamalar#

Ultralytics projelerine kod katkısında bulunurken şu en iyi uygulamaları aklında tut:

• Kod tekrarından kaçın: Mümkün olduğunca mevcut kodu yeniden kullan ve gereksiz bağımsız değişkenleri en aza indir.
• Daha küçük ve odaklanmış değişiklikler yap: Büyük ölçekli değişiklikler yerine hedefli değişikliklere odaklan.
• Mümkün olduğunda sadeleştir: Kodu sadeleştirme veya gereksiz bölümleri kaldırma fırsatlarını değerlendir.
• Uyumluluğu göz önünde bulundur: Değişiklik yapmadan önce, bunların Ultralytics kullanan mevcut kodu bozup bozmayacağını değerlendir.
• Tutarlı biçimlendirme kullan: Ruff Formatter gibi araçlar stil tutarlılığını korumana yardımcı olabilir.
• Uygun testler ekle: Yeni özelliklerin beklendiği gibi çalıştığından emin olmak için testler ekle.

Çekme İsteklerini İnceleme#

Çekme isteklerini incelemek, katkıda bulunmanın başka bir değerli yoludur. PR'ları incelerken:

• Birim testlerini kontrol et: PR'ın yeni özellikler veya değişiklikler için testler içerdiğini doğrula.
• Belge güncellemelerini incele: Değişiklikleri yansıtacak şekilde belgelerin güncellendiğinden emin ol.
• Performans etkisini değerlendir: Değişikliklerin performansı nasıl etkileyebileceğini değerlendir.
• CI testlerini doğrula: Tüm Sürekli Entegrasyon testlerinin başarıyla geçtiğini doğrula.
• Yapıcı geri bildirim sağla: Sorunlar veya endişeler hakkında özel ve net geri bildirim sun.
• Çabayı takdir et: Olumlu ve işbirlikçi bir ortamı korumak için yazarın çalışmasını takdir ettiğini göster.

Hataları Bildirme#

Hata bildirimlerine büyük değer veriyoruz; çünkü bunlar projelerimizin kalitesini ve güvenilirliğini geliştirmemize yardımcı olur. GitHub Issues üzerinden hata bildirirken:

• Mevcut sorunları kontrol et: Hatanın daha önce bildirilip bildirilmediğini görmek için önce ara.
• Bir Minimum Yeniden Üretilebilir Örnek sağla: Sorunu tutarlı biçimde yeniden üreten küçük ve kendi içinde yeterli bir kod parçacığı oluştur. Bu, verimli hata ayıklama için kritik öneme sahiptir.
• Ortamı açıkla: İşletim sistemini, Python sürümünü, ilgili kitaplık sürümlerini (ör. torch, ultralytics) ve donanımı (CPU/GPU) belirt.
• Beklenen ve gerçekleşen davranışı açıkla: Ne olmasını beklediğini ve gerçekte ne olduğunu net biçimde belirt. Hata mesajlarını veya geri izlemeleri de ekle.

Lisans#

Ultralytics, depoları için GNU Affero Genel Kamu Lisansı v3.0 (AGPL-3.0) kullanır. Bu lisans, yazılım geliştirmede açıklığı, şeffaflığı ve işbirliğine dayalı iyileştirmeyi teşvik eder. Tüm kullanıcıların yazılımı kullanma, değiştirme ve paylaşma özgürlüğüne sahip olmasını sağlayarak güçlü bir işbirliği ve yenilik topluluğunu destekler.

Tüm katkıcıların, Ultralytics açık kaynak topluluğuna etkili ve etik biçimde katkıda bulunabilmek için AGPL-3.0 lisansının koşullarını öğrenmesini teşvik ediyoruz.

YOLO Projeni AGPL-3.0 Lisansı Altında Açık Kaynaklı Yapma#

Projenizde Ultralytics YOLO modellerini veya kodunu mu kullanıyorsun? AGPL-3.0 lisansı, türetilmiş çalışmanın tamamını da AGPL-3.0 kapsamında açık kaynak hâline getirmeni gerektirir. Bu, açık kaynak temeller üzerine oluşturulan değişikliklerin ve daha büyük projelerin açık kalmasını sağlar.

AGPL-3.0 Uyumluluğu Neden Önemlidir?#

• Yazılımı Açık Tutar: İyileştirmelerin ve türetilmiş çalışmaların topluluğa fayda sağlamasını güvence altına alır.
• Yasal Gereklilik: AGPL-3.0 lisanslı kodu kullanmak, projenizi lisansın koşullarına bağlar.
• İşbirliğini Teşvik Eder: Paylaşımı ve şeffaflığı teşvik eder.

Projeni açık kaynak hâline getirmeyi tercih etmiyorsan bir Kurumsal Lisans almayı değerlendirebilirsin.

AGPL-3.0 ile Nasıl Uyumluluk Sağlanır?#

Uyumluluk, projenin tam karşılık gelen kaynak kodunu AGPL-3.0 lisansı kapsamında herkese açık hâle getirmek anlamına gelir.

1. Başlangıç Noktanı Seç:

   • Ultralytics YOLO'yu çatalla: Yakından bunun üzerine inşa ediyorsan Ultralytics YOLO deposunu doğrudan çatalla.
   • Ultralytics Şablonunu kullan: YOLO'yu entegre eden temiz ve modüler bir kurulum için Ultralytics şablon deposuyla başla.

2. Projen için lisans seç:

   • AGPL-3.0 lisansının tam metnini içeren bir LICENSE dosyası ekle.
   • Lisansı belirten bir bildirimi her kaynak dosyanın en üstüne ekle.

3. Kaynak Kodunu Yayımla:

   • Projenin kaynak kodunun tamamını herkese açık hâle getir (ör. GitHub'da). Buna şunlar dahildir:
     • YOLO modelini veya kodunu içeren eksiksiz, daha büyük uygulama ya da sistem.
     • Özgün Ultralytics YOLO kodunda yapılan tüm değişiklikler.
     • Eğitim, doğrulama ve çıkarım betikleri.
     • Değiştirilmiş veya ince ayar yapılmışsa model ağırlıkları.
     • Yapılandırma dosyaları, ortam kurulumları (requirements.txt, Dockerfiles).
     • Bir web uygulamasının parçasıysa arka uç ve ön yüz kodu.
     • Değiştirdiğin üçüncü taraf kitaplıkları.
     • Çalıştırmak veya yeniden eğitmek için gerekiyorsa ve yeniden dağıtılabiliyorsa eğitim verileri.

4. Açıkça Belgele:

   • Projenin AGPL-3.0 kapsamında lisanslandığını belirtmek için README.md dosyanı güncelle.
   • Projeni kaynak kodundan nasıl kuracağını, derleyeceğini ve çalıştıracağını açıkça anlatan yönergeler ekle.
   • Ultralytics YOLO'ya uygun şekilde atıfta bulun ve özgün depoya bağlantı ver. Örnek:

     This project utilizes code from [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.

Örnek Depo Yapısı#

Uygulamalı bir yapı örneği için Ultralytics Şablon Deposuna başvur:

my-yolo-project/
│
├── LICENSE               # Full AGPL-3.0 license text
├── README.md             # Project description, setup, usage, license info & attribution
├── pyproject.toml        # Dependencies (or requirements.txt)
├── scripts/              # Training/inference scripts
│   └── train.py
├── src/                  # Your project's source code
│   ├── __init__.py
│   ├── data_loader.py
│   └── model_wrapper.py  # Code interacting with YOLO
├── tests/                # Unit/integration tests
├── configs/              # YAML/JSON config files
├── docker/               # Dockerfiles, if used
│   └── Dockerfile
└── .github/              # GitHub specific files (e.g., workflows for CI)
    └── workflows/
        └── ci.yml

Bu yönergeleri izleyerek AGPL-3.0 uyumluluğunu sağlarken Ultralytics YOLO gibi güçlü araçları mümkün kılan açık kaynak ekosistemini desteklersin.

Sonuç#

Ultralytics açık kaynak YOLO projelerine katkıda bulunmaya gösterdiğin ilgi için teşekkür ederiz. Katılımın, yazılımımızın geleceğini şekillendirmek ve canlı bir yenilik ve işbirliği topluluğu oluşturmak için çok önemli. Kodu geliştiriyor, hata bildiriyor veya yeni özellikler öneriyor olman fark etmeksizin katkıların paha biçilmez.

Fikirlerinin hayata geçtiğini görmeyi sabırsızlıkla bekliyor ve nesne algılama teknolojisini ilerletme konusundaki bağlılığını takdir ediyoruz. Birlikte, bu heyecan verici açık kaynak yolculuğunda büyümeye ve yenilik yapmaya devam edelim.

SSS#