Halaman ini diterjemahkan oleh Cloud Translation API.

project global moja

Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.

Ringkasan project

Organisasi open source:: moja global
Penulis teknis:: Tlazypanda
Nama project:: Dokumentasi Panduan Orientasi Teknis untuk FLINT
Durasi project:: Durasi standar (3 bulan)

Project description

Dokumentasi Panduan Orientasi Teknis untuk FLINT guna memandu kontributor baru melalui orientasi teknis sehingga kontributor baru dapat memulai dengan mudah dengan dukungan minimum dari pengelola.

Masalah Project

Berikut adalah daftar masalah paling krusial yang terkait dengan dokumentasi saat ini: - Petunjuk panduan penyiapan lokal yang tidak teratur sehingga menyulitkan kontributor baru untuk memulai. - Beberapa repositori FLINT tidak memiliki dokumentasi tentang tujuannya dan tidak ditautkan satu sama lain sehingga menyulitkan pendatang baru untuk mengidentifikasi repositori mana yang akan diinstal. - Penginstalan Windows terdokumentasi dengan baik, tetapi dokumentasi penginstalan berbasis Linux masih perlu ditingkatkan. - Alur kerja Git saat ini bukan bagian dari dokumentasi

Solusi yang Diusulkan

Proposal ini menyajikan solusi untuk memandu kontributor baru melalui orientasi teknis sehingga kontributor baru dapat memulai dengan mudah dengan dukungan minimum dari pengelola. Hal ini dapat dicapai dengan memfaktorkan ulang dokumentasi saat ini agar mudah digunakan bagi pemula dan juga memelihara repositori mandiri pusat untuk semua dokumentasi yang tersedia. Project ini dibagi menjadi tiga fase:- - Meninjau dokumentasi dan pemfaktoran ulang yang ada: Tujuan fase ini adalah meninjau panduan saat ini dan memfaktorkan ulang panduan tersebut sedemikian rupa sehingga ringkas dan mudah dipahami oleh kontributor baru. Dokumentasi juga perlu diubah agar lebih mudah digunakan oleh pemula dengan menambahkan badge, emoji, dan informasi tentang masalah yang diberi tag khusus pemula atau masalah bagus untuk memulai. - Membuat repositori dokumentasi mandiri pusat: Tujuan fase ini adalah untuk menautkan semua dokumentasi yang tersedia dalam urutan logis yang berurutan di repositori mandiri. Langkah ini termasuk menyusun panduan kontribusi, petunjuk penyiapan proyek, dan panduan langkah demi langkah. - Menambahkan alur kerja Developer dan situs komunitas untuk developer baru: Tujuan fase ini adalah menambahkan alur kerja Developer yang berisi panduan kontribusi git dan arsitektur teknologi project beserta panduan pengujian dan QA. Situs komunitas yang diusulkan akan berupa aplikasi web satu halaman yang menampilkan alur kerja, masalah pertama kali yang dapat diklaim oleh kontributor baru, dan daftar semua kontributor. Fase 1: Tinjau dokumentasi yang ada dan pemfaktoran ulang:

Ubah dokumentasi saat ini dari repositori berikut: - FLINT: Dokumentasi saat ini tidak terlalu mendetail dan tidak memberikan urutan berurutan dari library prasyarat yang diperlukan. Panduan petunjuk langkah demi langkah dibagi menjadi beberapa file PDF, tetapi dapat disatukan di satu tempat dengan cara yang lebih ringkas. Selain itu, panduan penginstalan ini juga disesuaikan untuk Windows, tetapi untuk penginstalan Linux yang dialihkan ke repositori FLINT.docker mungkin bermanfaat. - FLINT.docker: Dokumentasi saat ini tidak memberikan tujuan di balik penyiapan repositori ini, yaitu untuk menyediakan penginstalan Linux FLINT melalui docker. Dukungan melalui Docker hanya terbatas pada Ubuntu 18.04 (Bionic Beaver) tetapi dapat diperluas ke distribusi berbasis Linux lainnya. Dokumentasi saat ini juga perlu menekankan cara berurutan untuk menyiapkan dockerfile dan juga informasi yang cukup tentang cara mem-build dari makefile. - FLINT.example: Dokumentasi saat ini tidak memberikan tujuan di balik penyiapan repositori ini, yaitu memberikan contoh cara menggunakan FLINT. Perbedaan dalam menjalankan sampel dapat dipisahkan dengan lebih baik dengan petunjuk spesifik untuk menjalankannya. Kita juga perlu menautkan repositori ini ke repositori FLINT utama yang memberi pengguna cara untuk membukanya guna melihat contoh yang sedang berjalan.

Informasi berikut perlu ditambahkan ke dokumentasi saat ini: - Penggunaan Git dan GitHub: Ini akan mencakup petunjuk langkah demi langkah tentang cara melakukan fork, meng-clone, lalu menetapkan upstream jarak jauh untuk repositori. Bagian ini juga akan memberikan informasi tentang cara melakukan rebase terhadap master terbaru dan menangani konflik penggabungan. - Badge & Emoji: Dokumentasi saat ini tidak memiliki Badge dan Emoji yang dapat membantu kontributor baru merasa diterima dan menemukan masalah yang tidak terlalu menakutkan. - Informasi tentang edisi Pertama Kali/Cocok untuk Pemula: Hal ini akan membantu mengalihkan kontributor baru ke edisi yang cocok untuk pemula dan situs komunitas. - Informasi tentang repositori Import-me: Repositori Import-me berfungsi sebagai template dasar pengukuran untuk memulai repositori Moja Global. Dokumentasi saat ini tidak menyebutkan pentingnya hal tersebut. Artikel ini perlu diperbarui untuk menyebutkan repositori Import-me dan langkah-langkah untuk memilihnya sebagai template saat membuat repositori baru juga perlu ditambahkan. Harus ada juga proses yang ditetapkan bagi coder untuk menyarankan fitur tambahan untuk repositori Import-me.

Tahap 2: Membuat repositori dokumentasi mandiri yang terpusat :

Alat yang akan digunakan untuk platform hosting:

Alat yang diusulkan untuk platform hosting ini adalah Read The Docs karena alasan berikut:- - Peringkat tinggi di antara berbagai platform hosting. - Pembaruan otomatis saat melakukan commit - Mudah disiapkan dan dukungan pemecahan masalah tersedia dengan mudah karena komunitas yang menggunakannya sangat besar - Dokumentasi diformat menggunakan reStructuredText dan output dikompilasi oleh Sphinx.

Atur semua konten dengan cara berurutan yang logis:

Urutan konten yang diusulkan adalah sebagai berikut:- - Pengantar dokumentasi developer: Bagian ini akan membahas pengantar Moja Global dan FLINT. - Kontribusi: Bagian ini akan terdiri dari subbagian “Cara Berkontribusi” (dalam hal kode/melaporkan bug/terjemahan/dokumentasi/mengatur acara, dll.) dan “Kode Etik”. - Penyiapan Pengembangan: Bagian ini akan terdiri dari subbagian “Alur Kerja Git & GitHub”, “Penginstalan Windows”, “Penginstalan Linux”. - Alur Kerja Developer: Bagian ini akan terdiri dari diskusi tentang alat yang terintegrasi untuk pengujian dan cara melakukan pengujian manual pada permintaan pull Anda dan lainnya seperti yang didokumentasikan pada fase berikutnya. - Bergabunglah dengan kami: Bagian ini akan menyediakan berbagai forum sosial seperti channel Slack untuk terhubung dan bekerja sama dengan Moja Global.

Tahap 3: Menambahkan alur kerja developer dan situs komunitas untuk kontributor baru:

Dokumentasi Alur Kerja Developer:

Dokumentasi alur kerja developer akan terdiri dari subbagian berikut:

Tech Stack/Arsitektur yang digunakan dan berbagai modul dalam kode: Dokumentasi untuk membiasakan kontributor baru dengan Tech stack yang diterapkan, berbagai library dan modul codebase.
Alat pengujian dan cakupan terintegrasi: Memperkenalkan kontributor baru ke alat pipeline CI/CD yang digunakan untuk pengujian, Bot cakupan, dan Pemeriksaan Kualitas Otomatis yang dijalankan terhadap kode mereka. Selain itu, berikan panduan kepada mereka tentang siapa yang harus didekati jika pengujian gagal.
Bot yang digunakan untuk mempermudah alur kerja, misalnya - Zulipbot: Mendesain template konten untuk bot yang akan ditampilkan dan Dokumentasi yang tersedia untuk memungkinkan pengguna memahami bot dan bahkan meningkatkan konfigurasi bot dengan berkontribusi.
Pengujian dan pengiriman permintaan pull secara manual: Dokumentasi yang akan diberikan tentang cara menguji permintaan Pull secara manual terhadap standar tertentu dan mengupload hasilnya dalam bentuk screenshot/gif saat mengirimkan Permintaan Pull.
Panduan peninjauan permintaan pull yang harus diikuti oleh kontributor: Panduan tentang cara memberi tag pada tim tertentu untuk ditinjau dan menambahkan label seperti “perlu ditinjau” ke permintaan pull agar pengelola dapat merespons.

Situs Komunitas:

Situs komunitas akan memiliki fitur berikut:-

Informasi tentang Alur Kerja kami: Alur kerja akan terdiri dari serangkaian tindakan yang dapat dimulai oleh kontributor baru, yaitu - mengklaim masalah timer pertama, diikuti dengan membuat masalah timer pertama untuk orang lain dan membantu orang lain dengan memberikan masukan dan meninjau permintaan pull mereka.
Daftar Masalah khusus pemula: Daftar masalah yang secara khusus ditujukan untuk pemula atau kontributor baru.
Daftar Masalah yang sudah tidak berlaku: Daftar masalah yang belum ditangani dalam jangka waktu yang lama dan karenanya tersedia untuk dipilih oleh kontributor.
Daftar Kontributor: Daftar kontributor yang sejauh ini berkontribusi pada repositori Moja Global.
Kontributor Terbaru: Daftar kontributor yang baru-baru ini berkontribusi ke repositori Moja Global.
Link untuk bergabung ke forum chat: Informasi dan link untuk bergabung ke komunitas Slack guna menyelesaikan kueri mereka dan berdiskusi lebih lanjut tentang project.