Katkı Kılavuzu

Başlarken

Adım 1: Depoyu çatallayın ve yerel makinenize kopyalayın

# Clone the repository from your fork
git clone https://github.com/xxxxx/read-frog.git

# Enter the project directory
cd read-frog

# Add the upstream remote to sync with the original repository
git remote add upstream https://github.com/mengxi-ream/read-frog.git

Adım 2: Bağımlılıkları yükleyin ve geliştirmeye başlayın

# Install dependencies
pnpm i

# Start the development server
pnpm dev

Bu, uzantı geliştirme ortamını başlatacaktır. Uzantı otomatik olarak varsayılan tarayıcınızda açılacaktır.

Geliştirme İpuçları

pnpm Node.js Yönetimi ile npx'i kullanma

pnpm'nin yerleşik Node.js sürüm yönetimini kullanıyoruz (pnpm 10.14'te tanıtılmıştır). npx komutlarını çalıştırırken EBADDEVENGINES hatalarıyla karşılaşabilirsiniz. İki çözüm var:

Çözüm 1: npx yerine pnpm dlx veya pnpx kullanın

# Instead of npx
npx some-package@latest

# Use pnpm dlx
pnpm dlx some-package@latest

# Or use pnpx (alias for pnpm dlx)
pnpx some-package@latest

Çözüm 2: Node.js sürümünü pnpm ile hizalayın

npx'yi değiştirmek uygun olmadığında (örneğin, Claude Code'daki kullanıcı kapsamlı MCP kurulumları için), Node.js sürümünüzü hizalayın:

# Install and use the required Node.js version globally
pnpm env use --global 22.18.0

Uzantıyı belirli bir tarayıcıda açın

Tarayıcı yolunu açıkça belirtmek için kök dizinde /modify web-ext.config.ts dosyasını oluşturabilirsiniz.

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  binaries: {
      chrome: "path/to/your/chrome.exe",
      firefox: "path/to/your/firefox.exe",
      edge: "path/to/your/edge.exe"
    }
});

pnpm dev, uzantıyı otomatik olarak yükleyemiyor

Chrome 137 veya sonraki bir sürümünü kullanıyorsanız geliştirme için Chrome for Testing indirmeniz gerekir. details'e bakın.

Kalıcı Krom Profili

Varsayılan olarak web-ext, geliştirme komut dosyasını her çalıştırdığınızda yeni bir profil oluşturur.

Geliştirme oturumları arasında oturum açma bilgilerini, geliştirme aracı uzantılarını ve tarayıcı ayarlarını korumak istiyorsanız proje kökünde web-ext.config.ts oluşturun veya güncelleyin.

Kalıcı profil yapılandırması işletim sistemleri arasında biraz farklıdır:

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  chromiumArgs: ['--user-data-dir=./.wxt/chrome-data'],
});

Windows'ta WXT, chromiumProfile ve keepProfileChanges kullanılmasını önerir. chromiumProfile yolu mutlak olmalıdır, bu nedenle node:path'den resolve kullanın.

Avantajları: Profiliniz geliştirici oturumları arasında kalır, böylece şunları yapabilirsiniz:

• Devtools uzantılarını yükleyin
• Oturum açma bilgilerini hatırla
• Tarayıcı ayarlarını koru

💡 İpucu: Kalıcı profiller yalnızca Chromium tarayıcılar için geçerlidir. Her proje için ayrı bir profil dizini kullanmak üzere örneklerde .wxt/chrome-data değerini değiştirebilirsiniz.

Geliştirici Modunda Google Giriş Sorunları

Geliştirici modunda bir Google hesabıyla giriş yapmak istiyorsanız ve "Bu tarayıcı veya uygulama güvenli olmayabilir." hatasıyla karşılaşırsanız otomasyon algılamayı devre dışı bırakmanız gerekir.

Çözüm: web-ext.config.ts'nize chromiumArgs ekleyin:

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  chromiumArgs: ['--disable-blink-features=AutomationControlled'],
});

Bu, Google'ın otomatik tarayıcılardan gelen giriş girişimlerini engellemesine neden olan otomasyon algılamayı devre dışı bırakır.

Kesme Noktası Hata Ayıklama Sorunları

⚠️ Kesme noktası hata ayıklamasıyla ilgili sorunlarla karşılaşırsanız bunun nedeni Chrome DevTools'un yok sayma listesi ayarlarından kaynaklanıyor olabilir. Uzantılar tarafından eklenen içerik komut dosyaları otomatik olarak göz ardı edilebilir ve bu da kesme noktalarının başarısız olmasına neden olabilir.

Çözüm:

1. DevTools'u herhangi bir web sayfasında açın
2. Sağ üst köşedeki ayarlar simgesine (⚙️) tıklayın
3. Sol gezinme menüsünden "Listeyi yoksay"ı seçin
4. "Uzantılar tarafından eklenen içerik komut dosyaları" seçeneğinin işaretli olmadığından emin olun

macOS: Çok Fazla Açık Dosya Hatası (EMFILE)

macOS'ta pnpm dev çalıştırırken bu hatayla karşılaşırsanız:

Bunun nedeni Chokidar'ın (Vite/WXT) tarafından kullanılan dosya izleme kitaplığı varsayılan olarak macOS'un yerel FSEvents'ini kullanmasıdır; bu, izlenen her dosya için bir dosya tanımlayıcı gerektirir/directory. Büyük projeler sistem sınırını aşabilir).

Çözüm: Dosya tanımlayıcıları gerektirmeyen yoklama moduna geçmek için CHOKIDAR_USEPOLLING=true öğesini ayarlayın.

Proje kökünde .env dosyasını oluşturun veya güncelleyin:

# .env
CHOKIDAR_USEPOLLING=true

Bundan sonra pnpm dev EMFILE hatası olmadan çalışacaktır.

Not: Yoklama modu biraz daha yavaştır ve daha fazla CPU kullanır ancak dosya tanımlayıcı sınırı sorununu ortadan kaldırır.

Kod Gönderiliyor

Yeni bir şube oluştur

# For new features
git checkout -b feat/the-feature

# For bug fixes
git checkout -b fix/the-bug

# For docs modify
git checkout -b docs/the-docs

Şubeyi Birleştir

Uzak ana şube güncellenirse ve PR'mizde çakışmalar yaratırsa, uzak şubeyi önceden birleştirerek bu sorunu çözebilirsiniz. .

# Switch to the main branch
git checkout main

# Pull the latest code from upstream
git pull upstream main

# Switch back to your local branch
git checkout docs/xxxx

# Merge the main branch into your local branch
git rebase main

# Push the code again if there are conflicts after rebase
git push --force-with-lease origin docs/xxxx

# If there are no conflicts, push the code again
git push origin docs/xxxx

fatal: 'upstream' does not appear to be a git repository
fatal: Could not read from remote repository.

git remote add upstream https://github.com/mengxi-ream/read-frog.git

Çekme Talebi Oluşturuluyor

Çekme İsteği oluşturmadan önce değişikliklerinizi belgelemek için bir değişiklik kümesi eklemeniz gerekir.

Sürüm Artışlarını Anlamak

Değişikliklerinize göre uygun sürüm yükseltme türünü seçin:

• yama - Hata düzeltmeleri, yazım hataları, belge güncellemeleri, küçük iyileştirmeler
  • Örnek: Çeviri hatasını düzeltme, README'yi güncelleme, düğme stilini düzeltme, performans iyileştirmeleri
• küçük - Geriye dönük olarak uyumlu yeni özellikler
  • Örnek: Çeviriyi devre dışı bırak düğmesi ekleyin, kelime dışa aktarma özelliği ekleyin
• majör - Mevcut işlevselliği etkileyen önemli değişiklikler
  • Örnek: API yapısını değiştirin, kullanımdan kaldırılan özellikleri kaldırın, büyük yeniden düzenleme

Değişiklik Kümesi Ekleme

# Run the changeset command
pnpm changeset

# 1. Choose version bump type for each selected package
🦋  What kind of change is this for @read-frog/extension? (current version is 1.17.3)
❯ patch   # For bug fixes and minor improvements
  minor   # For new features
  major   # For breaking changes

# 2. Write a summary of your changes
🦋  Please enter a summary for this change (this will be in the changelog)
Summary >>> fix: translation button style

pnpm changeset çalıştırıldıktan sonra .changeset dizininde bir işaretleme dosyası oluşturulacaktır. Çekme İsteğini oluşturmadan önce değişiklikleriniz hakkında daha fazla ayrıntı sağlamak için bu dosyayı düzenleyebilirsiniz.

Daha sonra bir Çekme İsteği oluşturun ve birleştirilmesini bekleyin.

Taahhüt Sözleşmesi

Taahhüt mesajları yazmak için Conventional Commits spesifikasyonunu kullanıyoruz.

Ortam değişkenlerini ayarlama

Uzantıyı geliştirirken, geliştirme ortamına yönelik API anahtarları gibi ortam değişkenlerini otomatik olarak yüklemek için kök dizinde bir .env.development dosyası oluşturabilirsiniz.

# .env.development
WXT_OPENAI_API_KEY=xxx
WXT_DEEPSEEK_API_KEY=xxx

WXT, Vite kurallarına uygun olarak dotenv dosyalarını yükler. import.meta.env aracılığıyla uzantı kodundan erişilmesi gereken değişkenler WXT_ önekini kullanmalıdır.

Yalnızca tek bir komut için ortam değişkeni ayarlamanız gerekiyorsa sözdizimi kabuğunuza bağlıdır:

SKIP_FREE_API=true pnpm test

Varsayılan Windows kabukları macOS/Linux KEY=value command sözdizimini desteklemez. Bir komut bu nedenle başarısız olursa yukarıdaki PowerShell veya CMD formunu kullanın. Düzenli olarak kullandığınız WXT değişkenlerini .env.development içine koymayı tercih edin.

Çin'de Google API Testlerini Atlayın

Çin ana karasından katkıda bulunuyorsanız kodu göndermeniz gerektiğinde aşağıdaki komutu kullanın:

SKIP_FREE_API=true git push

Bu neden gerekli? Çünkü kod testleri push işlemi sırasında gerçekleştirilir, ancak Google'ın ücretsiz API hizmetine Çin ana karasında erişilemez. Bu, testlerin başarısız olmasına ve itmenin reddedilmesine neden olur. SKIP_FREE_API ortam değişkenini ayarlayarak Google testlerini atlıyoruz.

Ne tür PR'ler incelenecek ve birleştirilecek?

Katkılara Başlarken

Bu ilk PR'larınızdan biriyse ve katkıda bulunma konusunda ciddiyseniz, genellikle kalite sorunları nedeniyle reddedilmez. Bakımcılar sorunları tanımlamanıza ve geliştirme sürecimize ve kod stilimize uyum sağlamanıza yardımcı olacaktır. Ancak, şu yönergelere uymanızı önemle öneririz:

1. Depodaki "İyi İlk Sayı" gibi küçük sorunlarla başlayın. Küçük, basit PR'ler sorunsuz bir öğrenme süreci sağlar.
2. PR'nizin tüm GitHub Eylemlerini ve yerel testleri geçtiğinden emin olun.

PR'm neden bakımcılar tarafından incelenmiyor?

1. Kod tabanına alışmadan önce aşırı derecede karmaşık bir PR'ye katkıda bulundunuz ve bu da çok fazla gerekli değişikliğin yapılmasına neden oldu.
2. Kodunuz birçok temel hata içeriyor ve bakımcıların ciddiyetinizi sorgulamasına neden oluyor:
   • Kaldırılmayan, kullanılmayan kod parçacıkları
   • Aşırı tekrarlanan kod
   • Değişken ve işlev adları çok keyfi
   • Yapay zeka destekli geliştirmeyi teşvik ediyoruz ancak yapay zeka tarafından oluşturulan kodu dikkatli bir şekilde incelemediniz, bu da düşük kaliteli, sürdürülemez veya aşırı mühendislik gerektiren kodlara yol açıyor
3. Bakımcılar birçok kez değişiklik önerilerinde bulundu, ancak ya bunları uygulamadınız ya da değişiklikleriniz temel sorunları gidermedi.