Ana içeriğe geç

SERENDER'a Katkıda Bulunma

SERENDER'a katkıda bulunma konusundaki ilginiz için teşekkür ederiz! Bu belge, katkıda bulunanlar ve proje sorumluları için rehberlik ve bilgi sağlar.

İçindekiler

Başlangıç

Ön Gereksinimler

Katkıda bulunmadan önce aşağıdakilerin yüklü olduğundan emin olun:

  • .NET 9.0 SDK veya üstü
  • Docker Desktop (altyapı servisleri için)
  • Visual Studio 2022 veya VS Code
  • Git
  • Node.js (frontend katkıları için)

Geliştirme Ortamı Kurulumu

  1. Repository'yi Fork Edin 

    # GitHub'da repository'yi fork edin, sonra fork'unuzu clone edin
git clone [YOUR_FORK_URL]
cd [PROJECT_DIRECTORY]

  2. Upstream Remote Ayarlayın 

    git remote add upstream [ORIGINAL_REPOSITORY_URL]

  3. Bağımlılıkları Yükleyin 

    # .NET paketlerini restore edin
dotnet restore

# Altyapı servislerini başlatın
docker-compose up -d

  4. Kurulumu Doğrulayın 

    # Her şeyin çalıştığından emin olmak için testleri çalıştırın
dotnet test

Nasıl Katkıda Bulunulur

Katkı Türleri

Çeşitli katkı türlerini memnuniyetle karşılıyoruz:

  • Hata Düzeltmeleri: Sorunları çözmemize ve istikrarı artırmamıza yardım edin
  • Özellik Geliştirme: Yeni özellikler ve geliştirmeler uygulayın
  • Dokümantasyon: Rehberleri, API dokümantasyonunu ve kod yorumlarını geliştirin
  • Test: Test kapsamı ekleyin ve mevcut testleri geliştirin
  • Performans: Kodu optimize edin ve sistem performansını artırın
  • Güvenlik: Güvenlik açıklarını tespit edin ve düzeltin
  • Refactoring: Kod kalitesini ve sürdürülebilirliği artırın

İş Bulma

  • Açık biletler için Issues sekmesini kontrol edin
  • Yeni başlayanlar için good first issue etiketli sorunları arayın
  • Öncelikli öğeler için help wanted etiketli sorunları kontrol edin
  • Planlanan özellikler için Proje Yol Haritası'nı inceleyin

Geliştirme İş Akışı

Branch Stratejisi

GitFlow dallanma modelini takip ediyoruz:

  • main: Üretime hazır kod
  • develop: Özellikler için entegrasyon dalı
  • feature/*: Yeni özellikler ve geliştirmeler
  • bugfix/*: Develop dalı için hata düzeltmeleri
  • hotfix/*: Üretim için kritik düzeltmeler
  • release/*: Sürüm hazırlığı

Branch Adlandırma Konvansiyonu

feature/[issue-number]-brief-description
bugfix/[issue-number]-brief-description
hotfix/[issue-number]-brief-description
release/v[version-number]

Örnekler: - feature/123-add-user-authentication - bugfix/456-fix-memory-leak - hotfix/789-security-patch

Bir Özellik Üzerinde Çalışma

  1. Branch Oluşturun 

    git checkout develop
git pull upstream develop
git checkout -b feature/123-your-feature-name

  2. Değişiklikleri Yapın

  3. Temiz, iyi dokümante edilmiş kod yazın
  4. Kodlama standartlarını takip edin
  5. Gerektiğinde test ekleyin/güncelleyin

  6. Gerekirse dokümantasyonu güncelleyin

  7. Değişiklikleri Commit Edin 

    git add .
git commit -m "feat: kullanıcı kimlik doğrulama sistemi eklendi

- JWT token tabanlı kimlik doğrulama uygulandı
- Giriş/çıkış endpoint'leri eklendi
- Şifre doğrulama dahil edildi
- Auth servisi için unit testler eklendi

Closes #123"

  8. Push Edin ve PR Oluşturun 

    git push origin feature/123-your-feature-name

Kodlama Standartları

C# Rehberi

  • Microsoft C# Kodlama Konvansiyonları'nı takip edin
  • Public üyeler için PascalCase kullanın
  • Private üyeler için camelCase kullanın
  • Değişkenler ve metodlar için anlamlı isimler kullanın
  • Public API'leri XML yorumlarıyla dokümante edin
  • Metodları küçük ve odaklı tutun (max 20-30 satır)
  • Asenkron işlemler için async/await kullanın

Kod Stili

// Doğru
public async Task<UserDto> GetUserByIdAsync(int userId)
{
    if (userId <= 0)
        throw new ArgumentException("User ID must be positive", nameof(userId));

    var user = await _userRepository.GetByIdAsync(userId);
    return _mapper.Map<UserDto>(user);
}

// Yanlış
public UserDto GetUser(int id)
{
    var u = _repo.GetById(id);
    return new UserDto { Name = u.Name, Email = u.Email };
}

Proje Yapısı

Hexagonal Architecture ilkelerini takip edin:

├── Domain/              # Temel iş mantığı
├── Application/         # Kullanım durumları ve iş kuralları
├── Infrastructure/      # Dış bağımlılıklar
│   ├── Persistence/     # Veritabanı implementasyonu
│   ├── Bus/            # Message bus implementasyonu
│   └── Rest/           # HTTP API implementasyonu
├── Bootstrap/          # Uygulama giriş noktası
└── Test/               # Test projeleri

Test Gereksinimleri

Test Kapsamı

  • Yeni özellikler için minimum %80 kod kapsamı
  • Tüm iş mantığı için unit testler
  • API endpoint'leri için integration testler
  • Dış entegrasyonlar için contract testler

Test Kategorileri

  1. Unit Testler 

    [Test]
public async Task GetUserById_ValidId_ReturnsUser()
{
    // Arrange
    var userId = 1;
    var expectedUser = new User { Id = userId, Name = "John Doe" };
    _mockRepository.Setup(r => r.GetByIdAsync(userId))
                  .ReturnsAsync(expectedUser);

    // Act
    var result = await _userService.GetUserByIdAsync(userId);

    // Assert
    Assert.That(result.Id, Is.EqualTo(userId));
    Assert.That(result.Name, Is.EqualTo("John Doe"));
}

  2. Integration Testler 

    [Test]
public async Task CreateUser_ValidData_ReturnsCreatedUser()
{
    // Arrange
    var newUser = new CreateUserRequest 
    { 
        Name = "Jane Doe", 
        Email = "jane@example.com" 
    };

    // Act
    var response = await _client.PostAsJsonAsync("/api/users", newUser);

    // Assert
    response.StatusCode.Should().Be(HttpStatusCode.Created);
    var user = await response.Content.ReadFromJsonAsync<UserDto>();
    user.Name.Should().Be("Jane Doe");
}

Testleri Çalıştırma

# Tüm testleri çalıştır
dotnet test

# Coverage ile çalıştır
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover

# Belirli test kategorisini çalıştır
dotnet test --filter Category=Unit

Pull Request Süreci

Göndermeden Önce

  • [ ] Tüm testlerin geçtiğinden emin olun
  • [ ] Kod kapsamı gereksinimleri karşılanıyor
  • [ ] Kod stil rehberlerini takip ediyor
  • [ ] Dokümantasyon güncellendi
  • [ ] Commit mesajları konvansiyonu takip ediyor
  • [ ] Branch hedef dal ile güncel

PR Şablonu

Pull request'leriniz için bu şablonu kullanın:

## Açıklama
Yapılan değişikliklerin kısa açıklaması.

## Değişiklik Türü
- [ ] Hata düzeltmesi (mevcut işlevselliği bozmayan değişiklik)
- [ ] Yeni özellik (işlevsellik ekleyen değişiklik)
- [ ] Breaking change (mevcut işlevselliğin çalışmamasına neden olan düzeltme veya özellik)
- [ ] Dokümantasyon güncellemesi

## Test
- [ ] Unit testler eklendi/güncellendi
- [ ] Integration testler eklendi/güncellendi
- [ ] Manuel test tamamlandı

## İlgili Sorunlar
Closes #[issue_number]

## Ekran Görüntüleri (varsa)
Değişikliklerinizi açıklamaya yardımcı olmak için ekran görüntüleri ekleyin.

## Kontrol Listesi
- [ ] Kodum stil rehberlerini takip ediyor
- [ ] Kodumun kendi kendini incelemesini gerçekleştirdim
- [ ] Özellikle anlaşılması zor alanlarda kodumu yorumladım
- [ ] Dokümantasyonda karşılık gelen değişiklikleri yaptım
- [ ] Değişikliklerim yeni uyarılar üretmiyor
- [ ] Düzeltmemin etkili olduğunu veya özelliğimin çalıştığını kanıtlayan testler ekledim
- [ ] Yeni ve mevcut unit testler değişikliklerimle yerel olarak geçiyor

İnceleme Süreci

  1. Otomatik Kontroller: CI/CD pipeline otomatik olarak çalışır
  2. Kod İncelemesi: En az bir proje sorumlusu kodu inceler
  3. Test: QA ekibi değişiklikleri test eder (varsa)
  4. Onay: Proje sorumlusu onaylar ve PR'ı merge eder

Sorun Bildirimi

Hata Raporları

Hata raporu şablonunu kullanın:

**Hatayı açıklayın**
Hatanın ne olduğuna dair açık ve özlü bir açıklama.

**Yeniden üretmek için**
Davranışı yeniden üretmek için adımlar:
1. '...' kısmına gidin
2. '....' üzerine tıklayın
3. '....' kısmına doğru kaydırın
4. Hatayı görün

**Beklenen davranış**
Ne olmasını beklediğinize dair açık ve özlü bir açıklama.

**Ekran görüntüleri**
Varsa, sorununuzu açıklamaya yardımcı olmak için ekran görüntüleri ekleyin.

**Ortam:**
 - OS: [örn. Windows 10]
 - .NET Versiyonu: [örn. 9.0]
 - Tarayıcı: [örn. chrome, safari]
 - Versiyon: [örn. 22]

**Ek bağlam**
Sorun hakkında diğer bağlamları buraya ekleyin.

Özellik İstekleri

Özellik isteği şablonunu kullanın:

**Özellik isteğiniz bir sorunla ilgili mi? Lütfen açıklayın.**
Sorunun ne olduğuna dair açık ve özlü bir açıklama.

**İstediğiniz çözümü açıklayın**
Ne olmasını istediğinize dair açık ve özlü bir açıklama.

**Düşündüğünüz alternatifleri açıklayın**
Düşündüğünüz alternatif çözümler veya özellikler hakkında açık ve özlü bir açıklama.

**Ek bağlam**
Özellik isteği hakkında diğer bağlamları veya ekran görüntülerini buraya ekleyin.

Proje Sorumlusu Rehberi

Sorumluluklar

Kod Sorumluları: - Pull request'leri incele ve merge et - Kod kalitesi ve standartları sağla - Katkıda bulunanlara geri bildirim ver - Sürümleri ve versiyonlamayı yönet - Proje sağlığını izle

Topluluk Sorumluları: - Tartışmaları ve sorunları moderate et - Yeni katkıda bulunanlara yardım et - Dokümantasyonu sürdür - Topluluk etkinlikleri düzenle

İnceleme Rehberi

  1. Kod Kalitesi
  2. Kodlama standartlarını takip ediyor
  3. Uygun test kapsamına sahip
  4. Dokümantasyon güncellendi

  5. Güvenlik açığı yok

  6. Fonksiyonel Gereksinimler

  7. Kabul kriterlerini karşılıyor
  8. Mevcut işlevselliği bozmuyor

  9. Performans etkisi kabul edilebilir

  10. İnceleme Kontrol Listesi

  11. [ ] Kod uyarı olmadan derleniyor
  12. [ ] Testler geçiyor ve kapsam yeterli
  13. [ ] Kod proje konvansiyonlarını takip ediyor
  14. [ ] Dokümantasyon güncellendi
  15. [ ] Güvenlik konuları ele alındı
  16. [ ] Performans etkisi kabul edilebilir

Merge Gereksinimleri

  • Büyük değişiklikler için 2 onay gerekli
  • Küçük değişiklikler için 1 onay gerekli
  • Merge'den önce tüm kontroller geçmeli
  • Feature branch'ler için Squash and merge
  • Release branch'ler için Merge commit

Sürüm Süreci

Versiyonlama

Semantic Versioning (SemVer) takip ediyoruz: - MAJOR: Breaking değişiklikler - MINOR: Yeni özellikler (geriye uyumlu) - PATCH: Hata düzeltmeleri (geriye uyumlu)

Sürüm Adımları

  1. Release Branch Oluştur 

    git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

  2. Versiyon Numaralarını Güncelle

  3. Assembly versiyonlarını güncelle
  4. package.json dosyalarını güncelle

  5. CHANGELOG.md'yi güncelle

  6. Final Test

  7. Tam test paketi çalıştır
  8. Manuel test gerçekleştir

  9. Güvenlik taraması yap

  10. Release PR Oluştur

  11. Release branch'den main'e PR oluştur
  12. Gerekli onayları al

  13. Main'e merge et

  14. Tag ve Deploy 

    git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

  15. Develop'ı Güncelle 

    git checkout develop
git merge main
git push origin develop

Topluluk

İletişim Kanalları

  • GitHub Issues: Hata raporları ve özellik istekleri
  • GitHub Discussions: Genel tartışmalar ve S&C
  • E-posta: [MAINTAINER_EMAIL] hassas konular için
  • Slack/Discord: [COMMUNITY_CHAT_LINK] gerçek zamanlı sohbet için

Yardım Alma

  • Mevcut Issues ve Discussions'ı kontrol edin
  • Dokümantasyon'u okuyun
  • Topluluk Sohbet'inde sorular sorun
  • Acil konular için doğrudan Proje Sorumluları'na ulaşın

Tanınma

Katkıda bulunanları şu yollarla tanıyoruz: - Tüm katkıda bulunanları listeleyen Contributors dosyası - Sürüm notları'nda önemli katkıları belirtme - Olağanüstü katkılar için Topluluk öne çıkarmaları - Tutarlı katkıda bulunanlar için Proje sorumlusu adaylıkları

Teşekkürler!

Katkılarınız bu projeyi herkes için daha iyi hale getiriyor. Birlikte harika bir şey inşa etmemize yardım etme konusundaki zamanınız ve çabanız için minnettarız!

Bu katkıda bulunma rehberi hakkında sorularınız için lütfen bir issue açın veya proje sorumlularıyla iletişime geçin.