diff --git a/docs/content/docs/meta.tr.json b/docs/content/docs/meta.tr.json index 730c020587..efc7116927 100644 --- a/docs/content/docs/meta.tr.json +++ b/docs/content/docs/meta.tr.json @@ -46,6 +46,7 @@ "keyboard-shortcuts", "---Geliştirme ve Topluluk---", "database-lab", + "plugin-development", "contributing" ] } diff --git a/docs/content/docs/plugin-development.tr.mdx b/docs/content/docs/plugin-development.tr.mdx new file mode 100644 index 0000000000..5efe86038f --- /dev/null +++ b/docs/content/docs/plugin-development.tr.mdx @@ -0,0 +1,204 @@ +--- +title: DBX Eklentisi Geliştirin ve Gönderin +description: DBX eklentileri oluşturun, imzasız inceleme adayları derleyin ve kaynak, çerçeve ile resmî Marketplace pull request'leri için doğru depoyu belirleyin. +--- + +DBX eklentileri; bağlantı türleri, workbench'ler, dosya sistemleri ve yerel sidecar'lar katkıda bulunabilen, bağımsız olarak kurulan `.dbxp` paketleridir. Eklenti kaynağı, DBX eklenti platformu ve resmî Marketplace kataloğu farklı depolara aittir. + + + **Marketplace listeleme pull request'leri `t8y2/dbx`'e değil [`t8y2/dbx-store`](https://github.com/t8y2/dbx-store) deposuna gider.** Bir eklentinin özellik kodu normalde yazarının kaynak deposunda kalır. Yalnızca DBX ana uygulamasını (host), SDK'yı, CLI'ı, protokolü, şemaları, dokümantasyonu ya da resmî örnekleri değiştirirken [`t8y2/dbx`](https://github.com/t8y2/dbx) deposuna PR açın. + + +## Değişiklik Hangi Depoya Gider + +| Değişiklik | Hedef | Resmî DBX PR'si mi? | +| --- | --- | --- | +| Eklentinizin ön yüzü, Rust/Go arka ucu, testleri ve yayın betikleri | Eklentinin kaynak deposu | `dbx`'e göndermeyin; kendi deposunda geliştirin ve yayınlayın | +| Yeni bir Marketplace kaydı, sürüm güncellemesi, simge ya da açıklama | [`t8y2/dbx-store`](https://github.com/t8y2/dbx-store) | Evet, hedef `main` | +| DBX eklenti ana uygulaması (host), Manifest/Marketplace şemaları, SDK, CLI ya da paketleyici | [`t8y2/dbx`](https://github.com/t8y2/dbx) | Evet, hedef `main` | +| Resmî örnekler ya da eklenti geliştirme dokümantasyonu | [`t8y2/dbx`](https://github.com/t8y2/dbx) | Evet | +| Belirli bir üçüncü taraf eklentisindeki hata | O eklentinin kaynak deposu | `dbx-store`'a göndermeyin | +| Özel ya da kurumsal bir gizli depo | Kendi gizli deponuz | Resmî Marketplace başvurusu gerekmez | +| Bir üretici JDBC sürücü JAR'ı | İki depoya da commit etmeyin | Kullanıcılar yerel makinede ya da sunucuda içe aktarır | + +Bağımsız bir yayın ritmine ihtiyaç duyan DBX bakımındaki eklentiler de normalde ayrı kaynak depolar kullanmalıdır. `t8y2/dbx`'e yalnızca ana uygulamayla sıkı şekilde bağlı örnekler, SDK doğrulama projeleri ya da bakımcıların açıkça kabul ettiği bileşenler ait olur. + +## Eklenti Proje Düzeni + +```text +my-plugin/ +├── manifest.json +├── dbx-plugin.toml +├── assets/ +├── ui/ +├── backend/ # ön yüz şablonunda bulunmaz +├── .github/workflows/ +│ └── plugin-release.yml +└── dist/ # üretilir; commit etmeyin +``` + +- `manifest.json` kimliği, sürümü, izinleri, giriş noktalarını ve katkı tanımlarını bildirir. +- `ui/` korumalı alanlı bir workbench içinde çalışır ve DBX ile Host API'leri üzerinden konuşur. +- `backend/` isteğe bağlı bir yerel sidecar'dır. Rust ve Go SDK'ları sağlanır; diğer diller DBX JSON-RPC protokolünü doğrudan uygulayabilir. +- `.dbxp` kurulabilir bir çıktı dosyasıdır, kaynak depo değildir. +- Yalnızca ön yüzden oluşan eklentiler tek bir `universal` paket yayınlayabilir. Yerel sidecar'lar her işletim sistemi ve CPU hedefi için ayrı paket gerektirir. + +## Workbench Bağlam Sözleşmesi + +Workbench bağlamı, DBX ile eklenti arasındaki sınırı geçen bir JSON veri anlık görüntüsüdür. Ana uygulama Vue reaktivitesini özyinelemeli olarak ayıklar ve bağımsız bir kopya gönderir; bu yüzden eklentiler Vue ref'leri, proxy'ler, DOM düğümleri, işlevler, bileşen örnekleri ya da kimlik bilgileri beklememelidir. + +Bağlam `null`, boolean, sonlu sayılar, dizeler, diziler ve düz nesneler içerebilir. Tanımsız nesne özellikleri atlanır ve tanımsız dizi öğeleri `null` olur. Date, Map, Set, symbol, bigint, sonlu olmayan sayılar, döngüsel referanslar ve özel sınıf örnekleri hatayla reddedilir. UTF-8 ile kodlanan bağlam 2 MiB ile sınırlıdır. + +`binding: "config"` kullanan bağlantı sağlayıcı alanları `external_config` içinde saklanır; `binding: "secret"` kullanan alanlar Secret Store'da saklanır. Eklenti bağlantı yapılandırması, oluşturma, düzenleme, kaydetme ve yeniden bağlanma akışları boyunca `external_config` değerini korur. + +## Eklenti Oluşturun + +Rust kurmadan ya da DBX kaynak kodunu indirmeden önceden derlenmiş CLI'ı kurun: + +```bash +npm install --global @dbx-app/plugin-cli +dbx-plugin --help +``` + +Ya da doğrudan `npx` üzerinden çalıştırın: + +```bash +npx @dbx-app/plugin-cli create my-ui-plugin --template frontend +``` + +npm paketi geçerli platform için önceden derlenmiş ikili dosyayı seçer ve eşleşen Rust ile Go eklenti SDK kaynaklarını birlikte paketler. Yalnızca ön yüzden oluşan eklentiler Rust ya da Go gerektirmez; yerel araç zincirleri yalnızca eklentinin kendi sidecar'ını derlerken gerekir. + +Bir proje oluşturun: + +```bash +# Yalnızca ön yüz, çapraz platform +dbx-plugin create my-ui-plugin --template frontend + +# Rust sidecar ve ön yüz +dbx-plugin create my-rust-plugin --template rust + +# Go sidecar ve ön yüz +dbx-plugin create my-go-plugin --template go +``` + +Üretilen projeyi eklentinin kendi kaynak deposunda geliştirin, test edin ve sürümleyin. Sıradan bir eklenti kaynak ağacını yalnızca yayınlamak için `t8y2/dbx` içine kopyalamayın. + +## İnceleme Adaylarını Derleyin + +Eklenti proje kökünden şunu çalıştırın: + +```bash +dbx-plugin package . +``` + +Komut yalnızca **imzasız inceleme adayları** üretir: + +```text +dist/--.dbxp +dist/--.artifact.json +``` + +Resmî eklenti yazarları DBX Store özel anahtarını oluşturmaz ve elinde bulundurmaz. Üretilen GitHub Release iş akışı her hedef için aday paketleri derler ve meta verilerini `release-candidates.json` içinde birleştirir. + +Yerel geliştirme sırasında imzasız bir paket kurmak için Plugin Center içindeki **Allow unsigned development packages** seçeneğini açıkça etkinleştirin. Bu seçenek resmî Marketplace doğrulamasını asla gevşetmez. + +## Resmî Marketplace Akışını Tamamlayın + +### 1. Adım: Kaynağı ve Aday Sürümü Yayınlayın + +Eklentinin kaynak deposunda bir sürüm etiketi ve GitHub Release oluşturun. Release şunları içermelidir: + +- desteklenen her hedef için bir imzasız `.dbxp` adayı; +- karşılık gelen `.artifact.json` dosyaları; +- birleştirilmiş `release-candidates.json`; +- yayın notları ve eşleşen kaynak etiketi. + +Aday paketler GitHub Releases'te, bir CDN'de ya da nesne depolamada bulunabilir. `.dbxp` ikili dosyalarını Git geçmişine commit etmeyin. + +### 2. Adım: dbx-store'da İnceleme Issue'su Açın + +[`t8y2/dbx-store` Issues](https://github.com/t8y2/dbx-store/issues/new/choose) sayfasını açın, **Plugin submission** seçeneğini seçin ve şunları belirtin: + +- eklenti kimliği, sürümü ve yayıncı; +- kaynak depo ve tam etiket; +- `release-candidates.json` dosyasının HTTPS URL'si; +- izinler, veri erişimi, ağ erişimi ve yerel sidecar davranışı; +- lisans, gizlilik politikası ve destek bağlantıları. + +Issue, imzalamadan önceki incelemenin giriş noktasıdır. Eklenti kaynağını `t8y2/dbx`'e göndermeyin ve resmî bir `signingKeyId` değeri kendiniz uydurmayın. + +### 3. Adım: DBX Store İnceler ve İmzalar + +Bakımcılar kaynağı, Manifest'i, izinleri, aday SHA-256 değerlerini, boyutları ve yerel davranışı inceler. Onaydan sonra korumalı DBX Store iş akışı: + +1. adayı, incelenen SHA-256 değeri ve boyutunu kullanarak indirir; +2. paketin imzasız olduğunu ve beklenen eklenti kimliği ile sürümüyle eşleştiğini doğrular; +3. DBX Store depo anahtarını kullanarak bir Ed25519 imzası ekler; +4. nihai `.dbxp` dosyasını, nihai artifact meta verisini ve imzalama makbuzunu yayınlar. + +Eklenti yazarları resmî depo özel anahtarını asla almaz. + +### 4. Adım: Listeleme PR'sini dbx-store'a Açın + +Nihai imzalı artifact meta verisini aldıktan sonra [`t8y2/dbx-store`](https://github.com/t8y2/dbx-store) deposunu fork'layın ve şunları ekleyin ya da güncelleyin: + +```text +publishers/.json # yalnızca yayıncının ilk başvurusu için +plugins/.json +catalog/index.json # doğrulama tarafından üretilir +``` + +Şunu çalıştırın: + +```bash +node scripts/validate.mjs +``` + +Ardından pull request'i şununla açın: + +```text +Base repository: t8y2/dbx-store +Base branch: main +``` + + + Yeni bir eklentinin nihai listeleme PR'si **yalnızca `t8y2/dbx-store`'a** gider. `t8y2/dbx` PR'si eklenti platformunun kendisine yapılan değişiklikler içindir; sıradan üçüncü taraf eklenti sürümlerini kaydetmek için değildir. + + +Bir listeleme PR'sine şunları eklemeyin: + +- `.dbxp` ikili dosyaları; +- kopyalanmış bir eklenti kaynak ağacı; +- Ed25519 özel anahtarları, token'lar ya da indirme kimlik bilgileri; +- nihai kurulum çıktısı olarak imzasız aday URL'leri; +- kendinizin atadığı bir `verified: true` değeri. + +## Mevcut Bir Eklentiyi Güncelleyin + +Her güncelleme yeni bir anlamsal sürüm kullanır. Mevcut Release varlıkları değiştirilemez: + +1. Eklenti kaynak deposunda yeni bir kaynak etiketi ve aday Release yayınlayın. +2. `t8y2/dbx-store` içinde yeni bir Plugin submission issue'su açın ve mevcut eklentiyle yeni sürüme atıfta bulunun. +3. Yeni adayların incelemesini ve depo imzalamasını tamamlamasını bekleyin. +4. `plugins/.json` dosyasını güncelleyen bir PR'yi `t8y2/dbx-store`'a açın. + +Eklenti kodu sorunlarını eklentinin kaynak deposunda düzeltin. `dbx-store`'a yalnızca katalog meta verisi, inceleme durumu, nihai URL'ler, karma (hash) değerleri, boyutlar ve Marketplace metni ait olur. + +## İmzalar ve Yayıncı Kimliği + +DBX şu anda tek bir depo imzası kullanır: + +- `publisher` yazarlığı ve Marketplace sahipliğini kaydeder; +- `signingKeyId` nihai kurulabilir paketi yayınlayan depo anahtarını tanımlar; +- DBX Store resmî eklentileri merkezi olarak inceler ve imzalar; +- özel depo işleticileri kendi depo anahtarlarını yönetir; +- geliştirici imzaları ve çift imzalar mevcut listeleme gereksinimleri değildir. + +Bir eklentinin Marketplace'te görünüp görünmeyeceğini insan incelemesi belirler. Ed25519 depo imzalaması, incelenen paketin sonradan değiştirilmediğini güvence altına alır. İmza, kaynak incelemesinin yerini tutmaz ve yerel sidecar'lar için bir işletim sistemi sandbox'ı değildir. + +## İlgili Dokümantasyon + +- [JDBC Eklentisi ve Veritabanı Sürücüleri](/tr/docs/plugins) +- [DBX Çekirdek Deposuna Katkıda Bulunun](/tr/docs/contributing) +- [`t8y2/dbx` eklenti platformu kaynağı](https://github.com/t8y2/dbx/tree/main/plugins) +- [`t8y2/dbx-store` resmî Marketplace deposu](https://github.com/t8y2/dbx-store)