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, depolarımızın kalitesini artırmaya yardımcı olmanın yanı sıra 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ıda bulunanların Davranış Kurallarımıza uyması gerekir. Saygı, nezaket ve profesyonellik, topluluğumuzun temelini oluşturur.

Çekme İstekleriyle Katkıda Bulunma#

Çekme istekleri (PRs) biçimindeki katkılara büyük değer veriyoruz. İnceleme sürecini olabildiğince sorunsuz hâle getirmek için şu adımları izle:

1. Depoyu çatalla: Önce ilgili Ultralytics deposunu (ör. ultralytics/ultralytics) GitHub hesabına çatalla.
2. Dal oluştur: Çatalladığın depoda, değişikliklerini yansıtan açık ve açıklayıcı bir adla 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 biçim kurallarına uyduğundan ve yeni hatalara ya da uyarılara yol açmadığından emin ol.
4. Değişikliklerini test et: Göndermeden önce, beklendiği gibi çalıştıklarını ve gerilemelere yol açmadıklarını doğrulamak için değişikliklerini yerel ortamında test et. Yeni işlevsellik ekliyorsan testler ekle.
5. Değişikliklerini işle: Değişikliklerini kısa ve açıklayıcı işlem mesajlarıyla kaydet. 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 deposunun main dalına ç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#

Çatalını (veya ana depoyu) klonla ve düzenlenebilir modda (-e) yükle; böylece Python yerel dosyalarını kullanır ve yeniden yükleme yapmadan her değişikliği alır:

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

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

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

Dokümantasyon Değişiklikleri#

Dokümantasyon kaynakları docs/en/ altında bulunur. PR açmadan önce depo kök dizininden geliştirme bağımlılıklarını yükle ve katı doğrulamanın tamamını çalıştır:

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

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

CLA İ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 etmesini sağlar.

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

I have read the CLA Document and I sign the CLA

Google Tarzı Docstring'ler#

Yeni işlevler veya sınıflar eklerken açık ve standartlaştırılmış dokümantasyon için Google tarzı docstring'ler ekle. Hem giriş hem de çıkış types öğelerini daima 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ştirilebilmeden önce GitHub Actions Sürekli Entegrasyon (CI) testlerini başarıyla geçmelidir. Bu testler, değişikliklerinin proje 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ı için En İyi Uygulamalar#

Ultralytics projelerine kod katkısında bulunurken şu en iyi uygulamaları göz önünde bulundur:

• Kod tekrarından kaçın: Mevcut kodu mümkün olduğunca yeniden kullan ve gereksiz bağımsız değişkenleri en aza indir.
• Daha küçük ve odaklı değişiklikler yap: Büyük ölçekli değişiklikler yerine hedefli düzenlemelere odaklan.
• Mümkün olduğunda basitleştir: Kodu basitleş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, Ultralytics kullanan mevcut kodları bozup bozmayacağını değerlendir.
• Biçimlendirmede tutarlı ol: Ruff Formatter gibi araçlar biçimsel tutarlılığı korumaya 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 de katkıda bulunmanın değerli bir yoludur. PR'ları incelerken:

• Birim testlerini kontrol et: PR'ın yeni özellikler veya değişiklikler için testler içerdiğini doğrula.
• Dokümantasyon güncellemelerini incele: Değişiklikleri yansıtacak şekilde dokümantasyonun güncellendiğinden emin ol.
• Performans etkisini değerlendir: Değişikliklerin performansı nasıl etkileyebileceğini göz önünde bulundur.
• CI testlerini doğrula: Tüm Sürekli Entegrasyon testlerinin başarılı olduğunu doğrula.
• Yapıcı geri bildirim ver: Sorunlar veya endişeler hakkında somut ve net geri bildirim sun.
• Harcanan emeği takdir et: Olumlu ve iş birliğine dayalı bir ortamı sürdürmek için yazarın çalışmasını takdir et.

Hataları Bildirme#

Hata raporlarına büyük önem veriyoruz; çünkü bu raporlar projelerimizin kalitesini ve güvenilirliğini artırmamıza yardımcı oluyor. GitHub Issues üzerinden hata bildirirken:

• Mevcut sorunları kontrol et: Hatanın daha önce bildirilip bildirilmediğini görmek için önce arama yap.
• Minimum Yeniden Üretilebilir Örnek sun: Sorunu tutarlı biçimde yeniden üreten, küçük ve kendi içinde yeterli bir kod parçacığı oluştur. Bu, hata ayıklama sürecinin verimli olması açısından çok önemlidir.
• Ortamı açıkla: İşletim sistemini, Python sürümünü, ilgili kütüphane sürümlerini (ör. torch, ultralytics) ve donanımını (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ında 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ğunun oluşmasına katkıda bulunur.

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

YOLO Projeni AGPL-3.0 Kapsamında Açık Kaynak Olarak Yayınlama#

Projenizde Ultralytics YOLO modellerini veya kodunu mu kullanıyorsun? AGPL-3.0 lisansı, türetilmiş çalışmanın tamamının da AGPL-3.0 kapsamında açık kaynak olarak yayınlanmasını gerektirir. Böylece açık kaynak temelleri üzerine kurulan değişikliklerin ve daha büyük projelerin açık kalması sağlanır.

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, projenin lisans koşullarına tabi olmasını gerektirir.
• İş birliğini teşvik eder: Paylaşımı ve şeffaflığı destekler.

Projeni açık kaynak hâline getirmemeyi tercih ediyorsan, Kurumsal Lisans edinmeyi düşünebilirsin.

AGPL-3.0 Lisansına Nasıl Uyulur?#

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

1. Başlangıç noktanı seç:

   • Ultralytics YOLO'yu çatalla: Projeyi Ultralytics YOLO üzerine yakından 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. Projene lisans ver:

   • AGPL-3.0 lisansının tam metnini içeren bir LICENSE dosyası ekle.
   • Her kaynak dosyasının başına lisansı belirten bir bildirim ekle.

3. Kaynak kodunu yayınla:

   • Projenin kaynak kodunun tamamını kamuya açık hâle getir (ör. GitHub'da). Buna şunlar dahildir:
     • YOLO modelini veya kodunu içeren daha büyük uygulamanın ya da sistemin tamamı.
     • Orijinal Ultralytics YOLO kodunda yaptığın 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 uç kodu.
     • Değiştirdiğin tüm üçüncü taraf kütüphaneler.
     • Çalıştırmak/yeniden eğitmek için gerekliyse 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.
   • Projenin kaynak kodundan nasıl kurulacağına, derleneceğine ve çalıştırılacağına ilişkin açık talimatlar ekle.
   • Ultralytics YOLO'ya uygun şekilde atıfta bulun ve orijinal 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ı#

Uygulanabilir bir yapı örneği için Ultralytics Şablon Deposuna bak:

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 de 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 açısından çok önemli. İster kodu geliştir, ister hata bildir, ister yeni özellikler öner; katkıların çok değerli.

Fikirlerinin hayata geçtiğini görmek için sabırsızlanıyoruz ve nesne algılama teknolojisini geliştirmeye yönelik kararlılığını takdir ediyoruz. Bu heyecan verici açık kaynak yolculuğunda birlikte büyümeye ve yenilik yapmaya devam edelim.

Sık Sorulan Sorular#