Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.
Proje özeti
- Açık kaynak kuruluşu:
- moja global
- Teknik yazar:
- Tlazypanda
- Proje adı:
- FLINT için Teknik Oryantasyon Kılavuzu dokümanları
- Proje uzunluğu:
- Standart uzunluk (3 ay)
Proje açıklaması
Yeni katkıda bulunanların, geliştiricilerden minimum düzeyde destek alarak kolayca çalışmaya başlayabilmesi için teknik oryantasyon sürecinde rehberlik etmek amacıyla FLINT için Teknik Oryantasyon Kılavuzu dokümanları.
Proje Sorunları
Mevcut dokümanlarla ilgili en önemli sorunların bir listesini aşağıda bulabilirsiniz: - Yerel kurulum kılavuzundaki talimatlar dağınık olduğundan yeni katkıda bulunanların başlaması zor. - FLINT'in birden çok deposu, amaçlarının belgelerini içermiyor ve birbirine bağlı değil. Bu da yeni kullanıcıların hangi deponun yükleneceğini belirlemesini zorlaştırıyor. - Windows kurulumu iyi belgelenmiş olsa da Linux tabanlı kurulum dokümanlarında iyileştirme yapılabilir. - Git iş akışı şu anda dokümanların bir parçası değildir
Önerilen Çözüm
Bu öneri, yeni katkıda bulunanlara teknik oryantasyon sürecinde rehberlik edecek bir çözüm sunar. Böylece yeni katkıda bulunanlar, bakım ekibinden minimum düzeyde destek alarak kolayca çalışmaya başlayabilir. Bu, mevcut dokümanları yeni başlayanlara uygun hale getirmek için yeniden yapılandırarak ve mevcut tüm dokümanlar için merkezi bir bağımsız depolama alanı sağlayarak yapılabilir. Proje üç aşamaya ayrılmıştır:- - Mevcut dokümanları inceleme ve yeniden düzenleme: Bu aşamanın amacı, mevcut kılavuzu inceleyip yeni katkıda bulunanlar tarafından anlaşılır ve kısa olacak şekilde yeniden düzenlemektir. Ayrıca, rozet, emoji ve "yalnızca ilk kez kullananlar için" veya "ilk sorun için iyi" etiketleriyle etiketlenen sorunlarla ilgili bilgiler ekleyerek dokümanları daha da yeni başlayanlara uygun hale getirmek için değiştirilmesi gerekiyor. - Merkezi, bağımsız bir doküman deposu oluşturun: Bu aşamanın amacı, mevcut tüm dokümanları mantıksal bir sırayla bağımsız bir depoda bağlamaktır. Katkı yönergeleri, proje oluşturma talimatları ve adım adım açıklamalı kılavuzlar bu kapsamdadır. - Yeni geliştiriciler için geliştirici iş akışı ve topluluk web sitesi ekleyin: Bu aşamanın amacı, test ve kalite kontrol kurallarının yanı sıra git katkı kuralları ve projenin teknik mimarisini içeren geliştirici iş akışını eklemektir. Önerilen topluluk web sitesi, iş akışını, yeni katkıda bulunanlar tarafından talep edilebilecek ilk katılımcı sorunlarını ve tüm katkıda bulunanların listesini gösteren tek sayfalık bir uygulama olacaktır. 1. Aşama: Mevcut belgeleri inceleme ve yeniden düzenleme:
Aşağıdaki depoların mevcut dokümanlarını değiştirin: - FLINT: Mevcut dokümanlar çok ayrıntılı değil ve gerekli önkoşul kitaplıklarının sıralı bir listesini sunmuyor. Adım adım talimat kılavuzları farklı PDF'lere ayrılmıştır ancak daha kısa bir şekilde tek bir yerde birleştirilebilir. Ayrıca, yükleme kılavuzları Windows için hazırlanmıştır ancak Linux yüklemesi için FLINT.docker deposuna yönlendirme faydalı olabilir. - FLINT.docker: Mevcut dokümanlar, bu deposunun kurulmasının amacını (FLINT'in Linux kurulumunu docker üzerinden sağlamak) belirtmiyor. Docker üzerinden destek yalnızca Ubuntu 18.04 (Bionic Beaver) ile sınırlıdır ancak diğer Linux tabanlı dağıtımlara genişletilebilir. Mevcut dokümanlar, docker dosyalarının sıralı olarak ayarlanmasına da vurgu yapmalı ve makefile'den nasıl derleneceği hakkında yeterli bilgi vermelidir. - FLINT.example: Mevcut dokümanlar, bu deposunun oluşturulmasındaki amacı (FLINT'in nasıl kullanılacağına dair bir örnek sunma) belirtmiyor. Farklı örnek çalıştırmalar, çalıştırılmaları için belirli talimatlarla daha iyi ayrılabilir. Ayrıca bu depoyu ana FLINT depomuza bağlamamız da gerekiyor. Böylece kullanıcılar burada, örneğin uygulamalı olarak göz atabilecekleri bir yöntemden yararlanabilecek.
Mevcut dokümanlara aşağıdaki bilgilerin eklenmesi gerekir: - Git ve GitHub kullanımı: Burada, deponun nasıl çatallanacağı, klonlanacağı ve ardından uzaktaki yayın kaynağının nasıl ayarlanacağıyla ilgili adım adım talimatlar yer alacaktır. Ayrıca, en son ana ağa göre yeniden temellendirme ve birleştirme anlaşmazlıklarını ele alma hakkında bilgi de sağlar. - Rozetler ve emojiler: Mevcut dokümanlar, yeni katkıda bulunanların kendilerini kabul edilmiş hissetmesine ve sorunları daha az korkutucu bulmasına yardımcı olabilecek rozetler ve emojiler içermiyor. - İlk kez katılanlar/yeni başlayanlar için sorunlar hakkında bilgi: Bu, yeni katkıda bulunanların yeni başlayanlara uygun sorunlara ve topluluk web sitesine yönlendirilmesine yardımcı olur. - Import-me deposuyla ilgili bilgiler: Import-me deposu, herhangi bir Moja Global deposuna hızlı başlangıç yapmak için temel bir şablon görevi görür. Mevcut dokümanlar bu konudaki önemden bahsetmiyor. Import-me deposunu içe aktaracak şekilde güncellenmesi gerekiyor ve bunu yeni bir depo oluştururken şablon olarak seçmek için uygulanacak adımları da eklemeniz gerekiyor. Kod yazarlarının Import-me deposu için ek özellikler önermesi gereken bir süreç de olmalıdır.
2. Aşama: Merkezi, bağımsız bir doküman deposu oluşturun :
Barındırma platformu için kullanılacak araç:
Bu barındırma platformu için önerilen araçlar, aşağıdaki nedenlerden dolayı Read The Docs'tur:- - Farklı barındırma platformları arasında üst sıralarda yer alır. - Taahhüt gönderirken otomatik güncelleme - Kullanan geniş topluluk sayesinde kolayca ayarlanabilir ve sorun giderme desteği mevcut - Dokümanlar reStructuredText kullanılarak biçimlendirilir ve çıkış Sphinx tarafından derlenir.
Tüm içerikleri mantıklı ve sıralı bir şekilde düzenleyin:
Önerilen içerik sırası şu şekildedir:- - Geliştirici dokümanlarına giriş: Bu bölümde Moja Global ve FLINT'e giriş yapılacaktır. - Katkıda Bulunma: Bu bölümde, "Katkıda Bulunma Yolları" (kod/raporlama hataları/çeviri/dokümanlar/organizasyon etkinlikleri vb. açısından) alt bölümleri ve "Davranış Kuralları" alt bölümleri yer alacaktır. - Geliştirme Kurulumu: Bu bölüm "Git ve GitHub İş Akışı", "Windows Kurulumu", "Linux Kurulumu" alt bölümlerinden oluşur. - Geliştirici İş Akışı'nın test aşamasındaki ve manuel test sürecinin ardından yapılması gerekenler - Bize katılın: Bu bölümde, Moja Global ile bağlantı kurup çalışabilmeniz için Slack kanalları gibi çeşitli sosyal forumlar sağlanmaktadır.
3. Aşama: Yeni katkıda bulunanlar için geliştirici iş akışı ve topluluk web sitesi ekleyin:
Geliştirici iş akışı dokümanları:
Geliştirici iş akışı dokümanları aşağıdaki alt bölümlerden oluşur:
- Kullanılan teknoloji grubu/mimari ve koddaki çeşitli modüller: Yeni katkıda bulunanları, uygulanan teknoloji grubu, kod tabanının çeşitli kitaplıkları ve modülleri hakkında bilgilendirmek için dokümanlar.
- Entegre test ve kapsama araçları: Test için kullanılan CI/CD ardışık düzeni araçlarına yeni katkıda bulunanlar ekleyin. Bu katkıda bulunanların kodlarında kapsama botları ve otomatik kalite kontrolleri çalıştırılır. Ayrıca, testler başarısız olursa kime başvurmaları gerektiği konusunda da yol gösterin.
- İş akışını kolaylaştırmak için kullanılan bot'lar, ör.Zulipbot: Botların gösterileceği içerik şablonları tasarlama ve kullanıcıların botları anlamasını sağlamak ve katkıda bulunarak bot yapılandırmasını iyileştirmek için belgeler sunmak.
- Çekme isteklerini manuel olarak test etme ve gönderme: Çekme isteklerinin belirli standartlara göre manuel olarak nasıl test edileceği ve çekme isteklerinin gönderilmesi sırasında sonuçların ekran görüntüsü/gif olarak nasıl yükleneceği hakkında dokümanlar sağlanmalıdır.
- Katkıda bulunanların uyması gereken çekme isteği inceleme yönergeleri: Belirli ekiplerin inceleme için etiketlenmesi ve bakım ekiplerinin yanıt vermesine olanak tanımak için çekme isteğine "incelenmesi gerekiyor" gibi etiketler eklenmesi ile ilgili yönergeler.
Topluluk Web Sitesi:
Topluluk web sitesinde aşağıdaki özellikler yer alır:
- İş akışımız hakkında bilgi: İş akışı, yeni bir katkıda bulunanın ilk olarak yapabileceği işlemlerden (ör.ilk katılımcılar için bir sorun talep etme, ardından başka biri için ilk katılımcılar sorunu oluşturma ve geri bildirim sağlayıp çekme isteklerini inceleyerek diğer kullanıcılara yardımcı olma) oluşur.
- Yalnızca ilk zamanlayıcı sorunlarının listesi: Özellikle ilk kez kullananlar veya yeni katkıda bulunanlar için hazırlanan sorunların listesi.
- Eski sorunlar listesi: Uzun zamandır üzerinde çalışılmamış ve bu nedenle katkıda bulunanlar tarafından seçilebilecek sorunların listesi.
- Katkıda Bulunanlar Listesi: Şu ana kadar Moja Global depolarına katkıda bulunanların listesi.
- Son Katkıda Bulunanlar: Moja Global depolarına son zamanlarda katkıda bulunanların listesi.
- Sohbet forumlarına katılma bağlantıları: Sorgularını çözmek ve projeler hakkında daha fazla tartışma yapmak için Slack topluluğuna katılmayla ilgili bilgiler ve bağlantılar.