Ultralytics Açık Kaynak Projelerine Katkıda Bulunma
Ultralytics açık kaynaklı projelerimize katkıda bulunmayı düşündüğün için teşekkür ederiz. Katılımın, depolarımızın kalitesini artırmaya yardımcı olmakla kalmaz, bilgisayarlı görü topluluğunun tamamına da katkı sağlar. Bu kılavuz, başlamana yardımcı olacak açık yönergeler ve en iyi uygulamaları sunar.
İzle: Ultralytics deposuna nasıl katkıda bulunulur | Ultralytics modelleri, veri kümeleri ve belgeleri 🚀
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:
- Depoyu çatalla: Önce ilgili Ultralytics deposunu (ör. ultralytics/ultralytics) GitHub hesabına çatalla.
- 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). - 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.
- Değişikliklerini test et: Göndermeden önce, beklendiği gibi çalıştıklarını ve gerilemelere neden olmadıklarını doğrulamak için değişikliklerini yerel ortamda test et. Mevcut testler değişikliklerin çoğunu kapsadığından yeni testler genellikle gereksizdir; yeni bir test faydalı olacaksa, taklit testler yerine mevcut bir test dosyasına birkaç satır eklemeyi tercih et.
- 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.). - Çekme isteği oluştur: Dalından, özgün Ultralytics deposunun
maindalı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-branchDokü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.pyDoğ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 CLAGoogle 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)).
Bu örnek, Google tarzı standart docstring biçimini gösterir. En iyi okunabilirlik için işlev açıklamasının, bağımsız değişkenlerin, dönüş değerinin ve örneklerin nasıl açıkça ayrıldığına dikkat et.
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 == arg2GitHub 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.
Çekme İsteklerini İnceleme#
Çekme isteklerini incelemek de katkıda bulunmanın değerli bir yoludur. PR'ları incelerken:
- 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ı 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 destekler. 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ğu oluşturur.
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.
-
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.
-
Projene lisans ver:
- AGPL-3.0 lisansının tam metnini içeren bir
LICENSEdosyası ekle. - Her kaynak dosyasının başına lisansı belirten bir bildirim ekle.
- AGPL-3.0 lisansının tam metnini içeren bir
-
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.
- Projenin kaynak kodunun tamamını kamuya açık hâle getir (ör. GitHub'da). Buna şunlar dahildir:
-
Açıkça belgele:
- Projenin AGPL-3.0 kapsamında lisanslandığını belirtmek için
README.mddosyanı 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.
- Projenin AGPL-3.0 kapsamında lisanslandığını belirtmek için
Ö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.ymlBu 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'in açık kaynaklı YOLO projelerine katkıda bulunmak istediğin için teşekkür ederiz. İster kodu geliştir, ister hataları bildir ya da yeni özellikler öner; katılımın yazılımımızı ve topluluğumuzu şekillendirmeye yardımcı olur.
Nesne algılama teknolojisini geliştirme konusundaki bağlılığın için teşekkür eder, katkılarını bekleriz.
Sık Sorulan Sorular#
Ultralytics YOLO açık kaynak depolarına katkıda bulunmak, yazılımı geliştirerek tüm topluluk için daha sağlam ve zengin özellikli hâle getirir. Katkılar; kod iyileştirmeleri, hata düzeltmeleri, belge geliştirmeleri ve yeni özelliklerin uygulanmasını içerebilir. Ayrıca katkıda bulunmak, alanındaki diğer yetenekli geliştiriciler ve uzmanlarla iş birliği yapmanı, becerilerini ve itibarını geliştirmeni sağlar. Başlamakla ilgili ayrıntılar için Çekme İstekleri Yoluyla Katkıda Bulunma bölümüne bak.
Katılımcı Lisans Sözleşmesini (CLA) imzalamak için çekme isteğini gönderdikten sonra CLA botunun verdiği talimatları izle. Bu süreç, katkılarının AGPL-3.0 lisansı kapsamında uygun şekilde lisanslanmasını ve açık kaynak projesinin yasal bütünlüğünün korunmasını sağlar. Çekme isteğine şu ifadeyi içeren bir yorum ekle:
I have read the CLA Document and I sign the CLADaha fazla bilgi için CLA İmzalama bölümüne bak.
Google tarzı belge dizeleri, işlev ve sınıflar için açık ve öz belgeler sunarak kodun okunabilirliğini ve bakımını kolaylaştırır. Bu belge dizeleri, belirli biçimlendirme kurallarıyla işlevin amacını, bağımsız değişkenlerini ve dönüş değerlerini açıklar. Ultralytics YOLO'ya katkıda bulunurken Google tarzı belge dizelerini izlemek, eklemelerinin iyi belgelenmesini ve kolayca anlaşılmasını sağlar. Örnekler ve yönergeler için Google Tarzı Belge Dizeleri bölümünü ziyaret et.
Çekme isteğin birleştirilmeden önce tüm GitHub Actions Sürekli Entegrasyon (CI) testlerini geçmelidir. Bu testler, kodun 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 sorunları düzelt. CI süreci ve sorun giderme ipuçları hakkında ayrıntılı bilgi için GitHub Actions CI Testleri bölümüne bak.
Hata bildirmek için raporuna açık ve öz bir Minimum Yeniden Üretilebilir Örnek ekle. Bu, geliştiricilerin sorunu hızla belirleyip çözmesine yardımcı olur. Örneğinin sorunu yeniden üretmek için yeterli, ancak mümkün olduğunca küçük olduğundan emin ol. Hata bildirme adımlarıyla ilgili ayrıntılar için Hataları Bildirme bölümüne bak.
Projeninde AGPL-3.0 kapsamında lisanslanmış Ultralytics YOLO kodunu veya modellerini kullanırsan AGPL-3.0 lisansı, projenin tamamının (türetilmiş çalışmanın) yine AGPL-3.0 kapsamında lisanslanmasını ve eksiksiz kaynak kodunun kamuya açık hâle getirilmesini gerektirir. Bu, yazılımın açık kaynak niteliğinin türev çalışmalar boyunca korunmasını sağlar. Bu gereklilikleri karşılayamıyorsan bir Kurumsal Lisans edinmen gerekir. Ayrıntılar için Projeni Açık Kaynak Olarak Yayınlama bölümüne bak.
Yorumlar7
Bir soru sor, sonuçlarını paylaş veya başka birine yardım et.
Mehrab-Shahbazi
Hi I will be happy if yolo add a feature that use slding window object detection. i want to add it and pull request it. is it usefull feature? will you accebt it?(if the tests passes).
Mehrab-Shahbazi
by sliding window, i mean crop big images ti smaller tiles and at the end merge all results as one output.( it is usefull for big images as you know)
Glenn JocherUltralytics@Mehrab-Shahbazi thank you for your interest in contributing! Sliding window object detection for large images can indeed be useful. If implemented efficiently and the tests pass, we welcome your pull request for review. Please ensure the feature aligns with the repository's design principles. For guidance, refer to our contributing guide.
Mehrab-Shahbazi
thank for your reply
esssyjr
Good evening all. I am trying to make a contribution for the dataset. I have forked and created a new branch but I could not see the folder specified for dataset. Should I just submit the .zip file to the root together with the read me, and send a pull request? Also, in my Github desktop I am unable to see Jupyter notebook as a code editor, but I manage to open the ultralytics cloned file in jupyter notebook, and uploaded the dataset. is that a good practice? Sorry for silly questions, I am new to open source contibution.
Glenn JocherUltralytics@esssyjr thank you for your interest in contributing! For dataset contributions, please follow the Ultralytics Contribution Guide and submit your dataset in a directory with a clear structure, including
train/andval/folders as applicable. Place the README in the same directory. Regarding Jupyter Notebook, it's fine to use it for preparing your dataset, but ensure your final submission is in the proper format per the guidelines. If you have more questions, feel free to ask on GitHub.esssyjr
Thanks for the reply, I have successfully uploaded the zip and readme file in the a folder in root of the Ultralytics repository. I requested a pull request in which it pass all the test but merge have been blocked, waiting for a approve review. Thank YOU
