Berkontribusi pada Dokumentasi#

Selamat datang di panduan kontribusi dokumentasi Upside Down Labs! Panduan ini dirancang untuk semua orang - baik Anda benar-benar baru dalam pemrograman atau pengembang berpengalaman. Kami akan memandu Anda melalui setiap langkah dengan penjelasan yang jelas dan membantu Anda memecahkan masalah umum yang mungkin Anda temui.

🏫 Apa yang Akan Anda Pelajari#

Cara mengatur komputer Anda untuk berkontribusi
Cara membuat perubahan pada dokumentasi
Cara mengirimkan kontribusi Anda
Cara memecahkan masalah umum yang mungkin Anda temui

📃 Prasyarat (Yang Anda Butuhkan Sebelum Memulai)#

Sebelum kita mulai, Anda perlu menginstal beberapa alat di komputer Anda. Jangan khawatir - kami akan menjelaskan apa yang dilakukan masing-masing dan cara menginstalnya.

Python - Bahasa Pemrograman
- Kunjungi: https://www.python.org/downloads/
- Klik tombol kuning besar “Download Python”
- Jalankan file yang diunduh
- Klik “Install Now”
Important

Centang kotak yang bertuliskan “Add Python to PATH” selama instalasi
- Cara memverifikasi itu berhasil:
  - Buka Command Prompt (Windows) atau Terminal (Mac/Linux)
  - Ketik
  python --version
  - Anda harus melihat sesuatu seperti “Python 3.11.x”
Git - Sistem Kontrol Versi
- Kunjungi: https://git-scm.com/downloads
- Unduh versi untuk sistem operasi Anda
- Jalankan installer dengan pengaturan default
- Saat ditanya tentang “Adjusting your PATH environment,” pilih “Git from the command line and also from 3rd-party software”
- Cara memverifikasi itu berhasil:
  - Buka Command Prompt atau Terminal
  - Ketik
  git --version
  - Anda harus melihat sesuatu seperti “git version 2.x.x”
Akun GitHub - Ruang Kerja Online Anda
- Cara membuat akun:
  - Kunjungi: signup
  - Klik “Sign up”
  - Pilih nama pengguna (ini akan publik)
  - Gunakan alamat email Anda
  - Buat kata sandi yang kuat
  - Verifikasi akun Anda melalui email
VSCode (Visual Studio Code)
Microsoft Store (Recommended for Windows)
1. Open Microsoft Store
  - Click the Windows Start button
  - Type “Microsoft Store” and press Enter
  - Or click the Microsoft Store icon in your taskbar
2. Search for Visual Studio Code
  - Click the search box at the top
  - Type “Visual Studio Code”
  - Press Enter
3. Install VS Code
  - Click on “Visual Studio Code” (published by Microsoft)
  - Click the “Get” or “Install” button
  - Wait for the download and installation to complete (usually 2-5 minutes)
4. Launch VS Code
  - Click “Launch” when installation is complete
  - Or find “Visual Studio Code” in your Start menu
Direct Download (For All Platforms)

Visit Visual Studio Code Website: https://code.visualstudio.com/download

To learn about VSCode and its setup visit: https://code.visualstudio.com/docs

🛠️ Langkah Setup (Mempersiapkan Semuanya)#

Sekarang Anda telah menginstal alat-alat tersebut, mari kita atur ruang kerja Anda. Ikuti langkah-langkah ini persis seperti yang ditulis.

Windows

Langkah 1: Fork Repository (Buat Salinan Anda Sendiri)

Pikirkan “forking” seperti membuat fotokopi buku sehingga Anda dapat menulis catatan di dalamnya tanpa mempengaruhi yang asli.

Login ke akun GitHub Anda : login menggunakan kredensial yang Anda buat sebelumnya.
Sekarang Anda telah login ke GitHub, Anda siap membuat salinan Anda sendiri dari proyek dokumentasi.
Kunjungi repository resmi: upsidedownlabs/docs.upsidedownlabs.tech
Klik tombol Fork di sudut kanan atas halaman
GitHub akan membuat salinan pribadi proyek di akun Anda
Anda sekarang memiliki salinan Anda sendiri di github.com/YOUR-USERNAME/docs.upsidedownlabs.tech

Langkah 2: Clone Fork Anda (Unduh di Komputer Anda)

Sekarang kami akan mengunduh salinan fork Anda ke komputer Anda sehingga Anda dapat mengerjakannya, menggunakan Git di komputer Anda, ikuti instruksi langkah demi langkah yang diberikan: Anda juga dapat mengikuti panduan detail GitHub for cloning.

Navigasi ke tempat Anda ingin menyimpan proyek dengan membuka File Explorer (Windows + E).
Klik kanan di ruang kosong di Documents atau folder pilihan Anda. Kami merekomendasikan menggunakan Folder Documents.
Pilih “Open in Terminal” dari menu konteks dan jika Anda tidak melihat opsi ini, tahan Shift sambil klik kanan.
Sekarang Anda memiliki terminal terbuka di direktori pilihan Anda, clone repo fork Anda dengan perintah yaitu Unduh fork Anda ke komputer Anda:
```
git clone https://github.com/YOUR-USERNAME/docs.upsidedownlabs.tech
```
Ganti YOUR-USERNAME dengan nama pengguna GitHub Anda yang sebenarnya!

Apa yang terjadi: Git akan membuat folder baru bernama docs.upsidedownlabs.tech di lokasi Anda saat ini.
Setelah cloning selesai, masukkan perintah berikut, ini akan membuka Visual Studio Code dengan semua folder docs.upsidedownlabs.tech:
```
code ./docs.upsidedownlabs.tech
```

Langkah 3: Membuat virtual environment (Ruang Kerja Terisolasi)

Virtual environment seperti membuat ruang kerja terpisah untuk proyek ini sehingga tidak mengganggu proyek Python lain di komputer Anda.

Sekarang kami akan membuat dan mengaktifkan virtual environment menggunakan terminal terintegrasi VS Code:

Di terminal VS Code, buat virtual environment:
```
py -m venv .venv
```
Aktifkan virtual environment:
```
.venv\Scripts\activate
```

Langkah 4: Install Dependencies (Alat yang Diperlukan)

Dependencies seperti bahan untuk resep - sistem dokumentasi membutuhkan alat spesifik untuk bekerja.

pip install -r requirements.txt

Apa yang dilakukan ini: Mengunduh dan menginstal semua alat yang diperlukan untuk membangun dokumentasi.

Langkah 5: Bangun dan Pratinjau Dokumentasi

Sekarang mari kita lihat situs web dokumentasi berjalan di komputer Anda!

Install Python dari situs web resmi jika belum diinstal.
Bangun dokumentasi:

sphinx-autobuild . .build

Apa yang harus Anda lihat:

Perintah akan menampilkan beberapa teks dan kemudian mengatakan sesuatu seperti “Serving on http://127.0.0.1:8000”
Buka browser web Anda dan pergi ke http://127.0.0.1:8000
Anda harus melihat situs web dokumentasi Upside Down Labs!

Note

Jalankan perintah ini jika pembaruan terbaru tidak terlihat, ini akan membersihkan memori cache dan membangun ulang dokumentasi.

.\make.bat clean

Stop live server: Di terminal VSCode, tekan Ctrl+C.
Jika perintah di atas tidak berhasil membersihkan cache gunakan; Remove build directory di terminal VSCode:

rmdir /s/q .build

Linux

Untuk dilakukan.

✏️ Membuat Perubahan (Bagian Yang Menyenangkan!)#

Sekarang Anda siap berkontribusi! Berikut cara membuat perubahan pada dokumentasi.

Memahami Struktur File#

Dokumentasi ditulis dalam file dengan ekstensi .rst (reStructuredText). Pikirkan ini seperti dokumen Word, tetapi dengan kode pemformatan khusus.

Folder umum yang akan Anda kerjakan:

guides/ - Panduan tutorial dan how-to
hardware/ - Dokumentasi hardware
software/ - Dokumentasi software
index.rst - Halaman utama

Cari file .rst di repository yang ingin Anda edit menggunakan VSCode Explorer atau browsing di komputer Anda.
Di VSCode atau jika Anda menggunakan editor teks lain pilihan Anda buka file.
Buat perubahan yang diinginkan yaitu kontribusi pada dokumentasi.
Simpan file.
Periksa browser Anda (berjalan sebagai server lokal di http://127.0.0.1:8000)- perubahan harus muncul secara otomatis!

💾 Mengirimkan Perubahan Anda (Berbagi Pekerjaan Anda)#

Setelah Anda puas dengan perubahan Anda, berikut cara mengirimkannya ke UpsideDown Labs, ada dua cara:

Menggunakan Command Line

Langkah 1: Simpan Perubahan Anda ke Git

Periksa file apa yang Anda ubah:

git status

Tambahkan perubahan Anda:

git add .

Commit perubahan Anda dengan pesan (Tulis deskripsi singkat tentang apa yang Anda ubah):

git commit -m "Improve installation instructions for beginners"

Langkah 2: Unggah ke GitHub

git push origin main

Langkah 3: Buat Pull Request

Pergi ke fork Anda di GitHub (github.com/YOUR-USERNAME/docs.upsidedownlabs.tech)
Klik “Compare & pull request” (tombol ini muncul setelah Anda push perubahan)
Tulis judul dan deskripsi yang menjelaskan apa yang Anda ubah dan mengapa
Klik “Create pull request”

Menggunakan GUI

Langkah untuk Commit dan Push menggunakan VS Code GUI

Setelah Anda membuat semua perubahan dan kontribusi pada dokumentasi Simpan perubahan Anda ``Ctrl + S``.

Langkah 1: Buka panel Source Control

Klik ikon Source Control di sidebar kiri (terlihat seperti ikon cabang) atau tekan Ctrl + Shift + G.

Langkah 2: Stage perubahan Anda

Anda akan melihat daftar file yang diubah.
Arahkan kursor ke file dan klik ikon plus (+) untuk stage atau klik “Stage All Changes” di atas.

Langkah 3: Tulis pesan commit - Ketik pesan di kotak di atas yang bertuliskan “Message” (tekan Ctrl+Enter untuk commit pada ‘main’). Ini wajib menulis pesan.

Contoh:

Update README and fix typos

Langkah 4: Commit perubahan Anda

Tekan Ctrl + Enter ATAU klik ikon centang ✅ di atas panel Source Control.

Langkah 5: Push ke GitHub

Di status bar bawah atau kanan atas Source Control, klik “… menu” (More Actions) > “Push” atau klik ikon “Synchronize Changes” 🔄 di kiri bawah.

VS Code akan push commit Anda ke GitHub.

Untuk Pertama Kali? Anda Mungkin Diminta untuk Sign In

Jika ini pertama kali Anda menggunakan GitHub dengan VS Code, itu mungkin meminta Anda untuk:

Sign in dengan GitHub
Otorisasi VS Code untuk mengakses repo Anda
Konfigurasi nama pengguna/email Git (itu mungkin memandu Anda melalui itu).

Apa yang terjadi selanjutnya: Tim Upside Down Labs akan meninjau perubahan Anda dan menerimanya atau meminta modifikasi.

💡 Tips untuk Kontribusi yang Baik#

Tulis seperti Anda menjelaskan kepada teman - gunakan bahasa yang sederhana dan jelas
Pecah paragraf panjang - paragraf yang lebih pendek lebih mudah dibaca
Gunakan contoh - tunjukkan jangan hanya katakan
Uji instruksi Anda - pastikan itu benar-benar bekerja
Periksa kesalahan ketik - baca melalui perubahan Anda sebelum mengirimkan

Untuk Visual Studio Code: Jadikan pengalaman editing Anda bahkan lebih baik#

Buka panel Extensions atau Ctrl+Shift+X
Cari dan install extensions ini:
- “reStructuredText” - Menambahkan syntax highlighting dan preview
- “Python” - Dukungan Python yang lebih baik
- “GitLens” - Integrasi Git yang ditingkatkan
- “Live Preview” - Preview file HTML langsung di VS Code