Katkıda bulunma
Keymotion bir Rust çalışma alanı (workspace), bir Tauri 2 kabuğu ve React/TypeScript ile yazılmış bir arayüzden oluşur. Bu sayfa projeyi nasıl derleyeceğinizi, bir değişikliğin sürüme nasıl ulaştığını ve insanların klavyelerini koruyan kuralları anlatır. Issue, tartışma ve PR’ları Türkçe ya da İngilizce yazabilirsiniz.
Kurulum
Bölüm başlığı “Kurulum”Keymotion bir Windows uygulamasıdır: Windows’un HID, Bluetooth LE ve WebView2 bileşenlerini kullanır; CI da onu Windows’ta derleyip test eder. Gerekenler:
- Rust. Sürüm
rust-toolchain.toml’da sabittir; rustup onu ilkcargokomutunda kendiliğinden kurar. Sürümü yalnızca bilerek ve ayrı bir PR’la yükseltin. - Tauri’nin Windows için ön koşulları: Microsoft C++ derleme araçları ve WebView2. Ayrıntılar Tauri’nin ön koşullar sayfasında.
- Node.js 24 ve pnpm. pnpm sürümü
app/package.json’da (packageManager) sabittir.
-
Arayüzün bağımlılıklarını kurun:
Terminal window pnpm --dir app install -
Rust testlerini çalıştırın. Bu komut test etmenin yanında TypeScript tiplerini ve tarayıcıdaki sahte arka ucun verilerini
app/src/bindingsklasörüne yazar:Terminal window cargo test --workspace -
Arayüzün geliştirme sunucusunu başlatın (
http://127.0.0.1:1420):Terminal window pnpm --dir app dev -
İkinci bir terminalde uygulamayı derleyip başlatın:
Terminal window cargo build -p keymotion./target/debug/keymotion.exeHata ayıklama derlemesi arayüzünü geliştirme sunucusundan yükler; bu yüzden 3. adım açık kalmalı. Sunucu çalışmıyorsa pencere boş kalır.
Arayüz üzerinde uygulama ya da klavye olmadan çalışmak için 3. adım açıkken tarayıcıda http://127.0.0.1:1420/?mock=usb adresini açın. Arka ucun yerine Mimari sayfasında anlatılan sahte arka uç cevap verir.
Geliştirici aracı kb
Bölüm başlığı “Geliştirici aracı kb”crates/kb-cli, uygulamayla aynı crate’leri kullanan kb adlı komut satırı aracını derler. Çıktısı Türkçedir.
cargo run -p kb-cli -- list # bütün bağlantı modlarındaki klavyelercargo run -p kb-cli -- descriptors # üreticiye özel koleksiyonların rapor tanımlayıcılarıcargo run -p kb-cli -- read-colors # tuşlarda o an görünen renkler (yalnızca okur)cargo run -p kb-cli -- --help # öteki komutlarKlavyenin kalıcı belleğine yazan komutlar --yes olmadan çalışmaz. kb klavyeyle doğrudan konuşur: uygulamanın başka programlar, denenmemiş klavye yazılımı ve HID koleksiyonlarının şekli için yaptığı denetimleri yapmaz. Kullanmadan önce Keymotion’ı ve klavyeyle konuşan başka yazılımları kapatın.
Dallar ve PR’lar
Bölüm başlığı “Dallar ve PR’lar”| Dal | İçeriği |
|---|---|
main |
Yayımlanmış kod; GitHub’daki varsayılan dal. main’e yapılan her birleştirme bir sürümdür ve vX.Y.Z etiketi alır. |
develop |
İşlerin toplandığı yer. Her zaman derlenir ve testlerini geçer. |
develop’tan kısa ömürlü bir dal açın. Dal adları küçük harfli, İngilizce ve tireyle yazılır:feature/keymap-editor,fix/mirror-gamma,docs/…,chore/….- PR’ı
developdalına açın: GitHub varsayılan dal olanmain’i önerir, hedef dalı değiştirin. PR’ı tek bir değişiklikle sınırlı tutun. CI yeşil olunca PR tek commit’e indirilerek (squash) birleştirilir. - Açıklamada neyin değiştiğini, nedenini ve nasıl denediğinizi yazın.
- Değişiklik kullanıcıya görünüyorsa
CHANGELOG.md’de Unreleased başlığının altına bir satır ekleyin vesite/altındaki kullanıcı kılavuzunu Türkçe ve İngilizce güncelleyin. - Değişiklik davranışı etkiliyorsa onu yalnızca testlerde değil, çalışan uygulamada da deneyin.
- Commit mesajları İngilizce yazılır. İlk satır emir kipinde ve en çok 72 karakterdir; gövde nedenini anlatır.
- Kişisel veri commit’lemeyin: Bluetooth adresleri, kullanıcı adınızı içeren yerel yollar, takvim adresleri, anahtarlar.
Sürümleri proje sahibi çıkarır. Sürüm numarası Cargo.toml, app/package.json ve app/src-tauri/tauri.conf.json dosyalarında durur; tools/check-version.mjs üçünün aynı olduğunu denetler. Bir sürüm PR’ı develop’u main’e birleştirir; main’e atılan etiket sürüm iş akışını (.github/workflows/release.yml) başlatır. İş akışı kurulum dosyasını derler ve proje sahibinin yayımlayacağı taslak bir GitHub sürümü açar. Sürüm dosyaları yalnızca bu iş akışında, main’deki bir etiketten ve derleme önbelleği kullanılmadan üretilir. Sürümden sonra main, bir birleştirme commit’iyle develop’a geri birleştirilir; böylece develop hiçbir zaman main’in gerisinde kalmaz.
Denetimler
Bölüm başlığı “Denetimler”CI (.github/workflows/ci.yml), develop ya da main’e açılan her PR’da ve bu dallara yapılan her birleştirmede çalışır. İki işi vardır.
Build and test Windows’ta çalışır. Bir PR’ın birleştirilebilmesi için bu işin geçmesi gerekir.
| Denetim | Komut |
|---|---|
| Metin temizliği: bayt sırası işareti yok, UTF-8 geçerli, bozuk Türkçe karakter yok | node tools/check-text.mjs |
| Üretici dosyası yok (aşağıda) | node tools/check-vendor-files.mjs |
| Sürüm numarası üç dosyada da aynı | node tools/check-version.mjs |
| Sürüm betiklerinin testleri | node --test "tools/release/*.test.mjs" |
| TypeScript tip denetimi ve arayüzün derlenmesi | pnpm --dir app build |
| Tek bir uyarının bile kırmızı yaptığı ESLint | pnpm --dir app lint |
| rustfmt | cargo fmt --all -- --check |
| Uyarıları hata sayan Clippy | cargo clippy --workspace --all-targets -- -D warnings |
| Rust testleri | cargo test --workspace |
| TypeScript tipleri commit’lenmiş ve güncel | Testlerden sonra app/src/bindings’te değişiklik kalmamalı |
Supply chain, deny.toml ayarıyla cargo deny --locked check çalıştırır: lisanslar, güvenlik duyuruları, aynı crate’in birden çok sürümü ve crate kaynakları. Yeni bir güvenlik duyurusu depoda hiçbir şey değişmeden bu işi kırmızı yapabilir; bu yüzden ayrı bir iştir ve birleştirme şartı değildir.
Göndermeden önce aynı denetimleri kendiniz çalıştırın:
cargo fmt --all -- --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspacepnpm --dir app buildpnpm --dir app lintnode tools/check-text.mjsnode tools/check-vendor-files.mjsnode tools/check-version.mjscargo deny için aracı bir kez cargo install --locked cargo-deny ile kurun, sonra cargo deny check çalıştırın.
Bağımlılıklar
Bölüm başlığı “Bağımlılıklar”Dependabot her hafta develop’a güncelleme PR’ları açar. Bir bağımlılığı kendiniz eklediğinizde, çıkardığınızda ya da güncellediğinizde:
- Üçüncü taraf bildirimlerini
node tools/notices.mjsile yeniden üretin veapp/public/third-party-notices.txtdosyasını commit’leyin. Bunun için bir kezcargo install --locked --features cli cargo-aboutgerekir. - Henüz izin verilmemiş bir lisans önce incelenir, sonra bilerek
deny.tomlveabout.tomldosyalarına eklenir.
Klavyeyle çalışırken
Bölüm başlığı “Klavyeyle çalışırken”- Yalnızca ölçülmüş komutlar. Bir komut, ancak o klavyede ölçüldükten sonra eklenir: dikkatle bir kez gönderilir, cevabı denetlenir ve etkisi görülür.
kb-protocol’deki izin listesi bunun dışındaki her şeyi reddeder. Listeye ekleme yapan bir PR ölçümü anlatır: tarih, klavye yazılımının sürümü, kullanılan araç, ne gönderildiği, ne geldiği ve klavyenin ne yaptığı. Şimdiye kadar ölçülenler Protokol ayrıntıları sayfasında. - Klavye yazılımı (firmware), önyükleyici (bootloader) ve kablosuz güncelleme yolları kapalı kalır. Keymotion klavye yazılımını güncellemez ve hiçbir zaman güncellemeyecek.
kb-protocol’deki güvenlik denetimi bu dizileri reddeder; Bluetooth modülünde ise yazma işlevi hiç yoktur. Bunlardan birini gevşeten değişiklik kabul edilmez. - Yazmak kullanıcının isteğiyle olur. Uygulama klavyenin kalıcı belleğine yalnızca kullanıcı istediğinde yazar: Klavyeye kaydet ya da Klavyeye yükle gibi bir düğme, bir profili yüklemek ya da kullanıcının açtığı ve günlük yükleme sınırıyla çalışan Canlı ekran gibi bir özellik. Kaydırıcı sürüklenirken ya da başka bir işin yan etkisi olarak asla yazmaz. Önizlemeler, klavyenin yalnızca RAM’de tuttuğu canlı karelerle yapılır.
- Gerçek klavyede dikkatle deneyin.
- Yalnızca okuyan komutlarla başlayın (
kb list,kb descriptors,kb read-colors), sonra canlı karelere geçin (kb live), kalıcı belleğe en son yazın. - Başlamadan önce klavyenin kendi ayarlarını not edin ve denemeden sonra geri yazın. Klavye tuş atamalarını ve makrolarını geri okuyamaz.
- Her ekran yüklemesi kalıcı belleği silip yeniden yazar. Yüklemeleri az tutun ve modelin kare sınırını asla aşmayın.
- Kendinize ait bir klavye kullanın ve PR’da hangi klavye yazılımı sürümünde denediğinizi yazın.
- Yalnızca okuyan komutlarla başlayın (
Yeni bir modelden önce neyin ölçülmesi gerektiğini Başka bir klavyeye destek anlatır.
Üretici dosyaları
Bölüm başlığı “Üretici dosyaları”Klavyenin fabrika ekran animasyonu, üreticinin sürücüsü ve sürücünün dosyaları depoya, kurulum dosyasına ya da bir sürüme hiçbir zaman girmez. tools/check-vendor-files.mjs; programları, sürücüleri ve arşivleri (uzantısına ya da içeriğine bakarak), docs/media/ dışındaki GIF dosyalarını ve yolunda “factory” geçen görsel ya da ham veri dosyalarını reddeder. Uygulama fabrika animasyonunu kullanıcının kendi bilgisayarındaki resmi sürücüden yedekleyebilir; ama onu hiçbir zaman kendisiyle birlikte dağıtmaz.
Issue’lar ve tartışmalar
Bölüm başlığı “Issue’lar ve tartışmalar”Boş issue açılamaz; her issue bir formla başlar:
- Problem report (
bug.yml): bir şey ters gitti. Uygulamada Ayarlar › Sorun bildir, formun istediği bilgileri panoya kopyalar. - Keyboard support request (
keyboard.yml): Başka bir klavyeye destek sayfasına bakın. - Idea or improvement (
idea.yml): öneriler.
Sorular ve henüz olgunlaşmamış fikirler Discussions bölümüne yazılır. Güvenlik sorunları herkese açık bir issue’da değil, gizli yoldan bildirilir: SECURITY.md. Katılan herkes davranış kurallarını kabul etmiş sayılır.
Lisans
Bölüm başlığı “Lisans”Keymotion, tercihinize göre Apache License, Version 2.0 ya da MIT lisansı ile lisanslıdır (MIT OR Apache-2.0). Aksini belirtmediğiniz sürece projeye eklenmek üzere gönderdiğiniz her katkı da ek bir şart ya da koşul olmadan aynı şekilde lisanslanır.
Keymotion bağımsız bir projedir ve AJAZZ ile bir bağı yoktur; ayrıntı için NOTICE dosyasına bakın.