AGENTS.md

1# AGENTS.md
2 
3## Gambaran Proyek
4 
5Ini adalah repositori kurikulum edukasi untuk mengajarkan dasar-dasar pengembangan web kepada pemula. Kurikulum ini merupakan kursus komprehensif selama 12 minggu yang dikembangkan oleh Microsoft Cloud Advocates, menampilkan 24 pelajaran praktis yang mencakup JavaScript, CSS, dan HTML.
6 
7### Komponen Utama
8 
9- **Konten Edukasi**: 24 pelajaran terstruktur yang diorganisasi dalam modul berbasis proyek
10- **Proyek Praktis**: Terrarium, Permainan Mengetik, Ekstensi Browser, Permainan Luar Angkasa, Aplikasi Perbankan, Editor Kode, dan Asisten Chat AI
11- **Kuis Interaktif**: 48 kuis dengan 3 pertanyaan tiap kuis (penilaian sebelum/sesudah pelajaran)
12- **Dukungan Multi-bahasa**: Terjemahan otomatis untuk lebih dari 50 bahasa melalui GitHub Actions
13- **Teknologi**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (untuk proyek AI)
14 
15### Arsitektur
16 
17- Repositori edukasi dengan struktur berbasis pelajaran
18- Setiap folder pelajaran berisi README, contoh kode, dan solusi
19- Proyek mandiri di direktori terpisah (quiz-app, berbagai proyek pelajaran)
20- Sistem terjemahan menggunakan GitHub Actions (co-op-translator)
21- Dokumentasi disajikan melalui Docsify dan tersedia dalam format PDF
22 
23## Perintah Setup
24 
25Repositori ini terutama untuk konsumsi konten edukasi. Untuk bekerja dengan proyek khusus:
26 
27### Setup Repositori Utama
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Setup Aplikasi Kuis (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Mulai server pengembangan
40npm run build      # Bangun untuk produksi
41npm run lint       # Jalankan ESLint
42```
43 
44### API Proyek Bank (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Mulai server API
50npm run lint       # Jalankan ESLint
51npm run format     # Format dengan Prettier
52```
53 
54### Proyek Ekstensi Browser
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Ikuti petunjuk pemuatan ekstensi spesifik browser
60```
61 
62### Proyek Permainan Luar Angkasa
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Buka index.html di browser atau gunakan Live Server
68```
69 
70### Proyek Chat (Backend Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Tetapkan variabel lingkungan GITHUB_TOKEN
76python api.py
77```
78 
79## Alur Kerja Pengembangan
80 
81### Untuk Kontributor Konten
82 
831. **Fork repositori** ke akun GitHub Anda
842. **Clone fork Anda** secara lokal
853. **Buat cabang baru** untuk perubahan Anda
864. Lakukan perubahan pada konten pelajaran atau contoh kode
875. Uji perubahan kode di direktori proyek terkait
886. Ajukan pull request sesuai panduan kontribusi
89 
90### Untuk Pembelajar
91 
921. Fork atau clone repositori
932. Navigasi ke direktori pelajaran secara berurutan
943. Baca file README di setiap pelajaran
954. Selesaikan kuis sebelum pelajaran di https://ff-quizzes.netlify.app/web/
965. Kerjakan contoh kode di folder pelajaran
976. Selesaikan tugas dan tantangan
987. Ikuti kuis sesudah pelajaran
99 
100### Pengembangan Langsung
101 
102- **Dokumentasi**: Jalankan `docsify serve` di root (port 3000)
103- **Aplikasi Kuis**: Jalankan `npm run dev` di direktori quiz-app
104- **Proyek-proyek**: Gunakan ekstensi Live Server VS Code untuk proyek HTML
105- **Proyek API**: Jalankan `npm start` di direktori API terkait
106 
107## Instruksi Pengujian
108 
109### Pengujian Aplikasi Kuis
110 
111```bash
112cd quiz-app
113npm run lint       # Periksa masalah gaya kode
114npm run build      # Verifikasi keberhasilan build
115```
116 
117### Pengujian API Bank
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Periksa masalah gaya kode
122node server.js     # Verifikasi server mulai tanpa kesalahan
123```
124 
125### Pendekatan Pengujian Umum
126 
127- Ini adalah repositori edukasi tanpa pengujian otomatis lengkap
128- Pengujian manual fokus pada:
129  - Contoh kode berjalan tanpa error
130  - Link di dokumentasi berfungsi dengan baik
131  - Proses build proyek berjalan sukses
132  - Contoh sesuai praktik terbaik
133 
134### Pemeriksaan Sebelum Pengiriman
135 
136- Jalankan `npm run lint` di direktori dengan package.json
137- Verifikasi link markdown valid
138- Uji contoh kode di browser atau Node.js
139- Pastikan terjemahan mempertahankan struktur yang tepat
140 
141## Pedoman Gaya Kode
142 
143### JavaScript
144 
145- Gunakan sintaks ES6+ modern
146- Ikuti konfigurasi ESLint standar di proyek
147- Gunakan nama variabel dan fungsi yang bermakna untuk kejelasan edukasi
148- Tambahkan komentar penjelasan konsep untuk pembelajar
149- Format menggunakan Prettier jika dikonfigurasi
150 
151### HTML/CSS
152 
153- Elemen HTML5 semantik
154- Prinsip desain responsif
155- Penamaan kelas yang jelas
156- Komentar menjelaskan teknik CSS untuk pembelajar
157 
158### Python
159 
160- Panduan gaya PEP 8
161- Contoh kode jelas dan edukatif
162- Gunakan type hint bila membantu pembelajaran
163 
164### Dokumentasi Markdown
165 
166- Hierarki judul yang jelas
167- Blok kode dengan penentuan bahasa
168- Link ke sumber daya tambahan
169- Screenshot dan gambar di direktori `images/`
170- Teks alternatif untuk gambar demi aksesibilitas
171 
172### Organisasi File
173 
174- Pelajaran diberi nomor berurutan (1-getting-started-lessons, 2-js-basics, dll.)
175- Setiap proyek memiliki direktori `solution/` dan sering juga `start/` atau `your-work/`
176- Gambar disimpan di folder `images/` khusus pelajaran
177- Terjemahan disimpan dalam struktur `translations/{language-code}/`
178 
179## Build dan Deployment
180 
181### Deployment Aplikasi Kuis (Azure Static Web Apps)
182 
183quiz-app dikonfigurasi untuk deployment Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Membuat folder dist/
188# Menerapkan melalui workflow GitHub Actions saat push ke main
189```
190 
191Konfigurasi Azure Static Web Apps:
192- **Lokasi aplikasi**: `/quiz-app`
193- **Lokasi output**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Generasi PDF Dokumentasi
197 
198```bash
199npm install                    # Pasang docsify-to-pdf
200npm run convert               # Hasilkan PDF dari docs
201```
202 
203### Dokumentasi Docsify
204 
205```bash
206npm install -g docsify-cli    # Pasang Docsify secara global
207docsify serve                 # Layani di localhost:3000
208```
209 
210### Build Spesifik Proyek
211 
212Setiap direktori proyek mungkin memiliki proses build sendiri:
213- Proyek Vue: `npm run build` untuk membuat bundel produksi
214- Proyek statis: Tidak ada langkah build, layani file langsung
215 
216## Panduan Pull Request
217 
218### Format Judul
219 
220Gunakan judul jelas yang menggambarkan area perubahan:
221- `[Quiz-app] Tambahkan kuis baru untuk pelajaran X`
222- `[Lesson-3] Perbaiki typo di proyek terrarium`
223- `[Translation] Tambah terjemahan Spanyol untuk pelajaran 5`
224- `[Docs] Perbarui instruksi setup`
225 
226### Pemeriksaan Wajib
227 
228Sebelum mengirim PR:
229 
2301. **Kualitas Kode**:
231   - Jalankan `npm run lint` di direktori proyek terkait
232   - Perbaiki semua error dan peringatan lint
233 
2342. **Verifikasi Build**:
235   - Jalankan `npm run build` jika berlaku
236   - Pastikan tidak ada error build
237 
2383. **Validasi Link**:
239   - Uji semua link markdown
240   - Verifikasi referensi gambar berfungsi
241 
2424. **Tinjau Konten**:
243   - Proofreading tata bahasa dan ejaan
244   - Pastikan contoh kode benar dan edukatif
245   - Verifikasi terjemahan mempertahankan makna asli
246 
247### Persyaratan Kontribusi
248 
249- Setujui Microsoft CLA (pemeriksaan otomatis pada PR pertama)
250- Ikuti [Kode Etik Open Source Microsoft](https://opensource.microsoft.com/codeofconduct/)
251- Lihat [CONTRIBUTING.md](./CONTRIBUTING.md) untuk panduan rinci
252- Referensikan nomor isu dalam deskripsi PR jika ada
253 
254### Proses Review
255 
256- PR direview oleh pemelihara dan komunitas
257- Prioritaskan kejelasan edukasi
258- Contoh kode harus mengikuti praktik terbaik saat ini
259- Terjemahan direview untuk akurasi dan kesesuaian budaya
260 
261## Sistem Terjemahan
262 
263### Terjemahan Otomatis
264 
265- Menggunakan GitHub Actions dengan workflow co-op-translator
266- Menerjemahkan ke lebih dari 50 bahasa secara otomatis
267- File sumber di direktori utama
268- File terjemahan di direktori `translations/{language-code}/`
269 
270### Menambah Perbaikan Terjemahan Manual
271 
2721. Cari file di `translations/{language-code}/`
2732. Buat perbaikan sambil mempertahankan struktur
2743. Pastikan contoh kode tetap berfungsi
2754. Uji konten kuis yang sudah diterjemahkan
276 
277### Metadata Terjemahan
278 
279File terjemahan termasuk header metadata:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Debugging dan Pemecahan Masalah
293 
294### Masalah Umum
295 
296**Aplikasi kuis gagal mulai**:
297- Periksa versi Node.js (disarankan v14+)
298- Hapus `node_modules` dan `package-lock.json`, jalankan `npm install` lagi
299- Periksa konflik port (default: Vite menggunakan port 5173)
300 
301**Server API tidak mulai**:
302- Periksa versi Node.js minimal (node >=10)
303- Periksa apakah port sudah digunakan
304- Pastikan semua dependensi terinstall dengan `npm install`
305 
306**Ekstensi browser tidak dimuat**:
307- Periksa format manifest.json sudah benar
308- Periksa konsol browser untuk error
309- Ikuti instruksi instalasi ekstensi khusus browser
310 
311**Masalah proyek chat Python**:
312- Pastikan paket OpenAI terinstall: `pip install openai`
313- Verifikasi variabel lingkungan GITHUB_TOKEN sudah diset
314- Cek izin akses GitHub Models
315 
316**Docsify tidak menyajikan dokumentasi**:
317- Instal docsify-cli secara global: `npm install -g docsify-cli`
318- Jalankan dari direktori root repositori
319- Pastikan `docs/_sidebar.md` tersedia
320 
321### Tips Lingkungan Pengembangan
322 
323- Gunakan VS Code dengan ekstensi Live Server untuk proyek HTML
324- Instal ekstensi ESLint dan Prettier untuk format konsisten
325- Gunakan DevTools browser untuk debugging JavaScript
326- Untuk proyek Vue, pasang ekstensi Vue DevTools browser
327 
328### Pertimbangan Performa
329 
330- Jumlah file terjemahan besar (50+ bahasa) membuat clone penuh besar
331- Gunakan clone shallow jika hanya bekerja dengan konten: `git clone --depth 1`
332- Kecualikan terjemahan dari pencarian saat bekerja dengan konten bahasa Inggris
333- Proses build mungkin lambat pada run pertama (npm install, build Vite)
334 
335## Pertimbangan Keamanan
336 
337### Variabel Lingkungan
338 
339- API key tidak boleh disimpan di repositori
340- Gunakan file `.env` (sudah ada di `.gitignore`)
341- Dokumentasikan variabel lingkungan yang diperlukan di README proyek
342 
343### Proyek Python
344 
345- Gunakan virtual environment: `python -m venv venv`
346- Jaga dependensi tetap terupdate
347- Token GitHub harus punya izin minimal yang dibutuhkan
348 
349### Akses GitHub Models
350 
351- Token Akses Pribadi (PAT) diperlukan untuk GitHub Models
352- Token harus disimpan sebagai variabel lingkungan
353- Jangan pernah commit token atau kredensial
354 
355## Catatan Tambahan
356 
357### Sasaran Audiens
358 
359- Pemula lengkap di pengembangan web
360- Pelajar dan pembelajar mandiri
361- Guru yang menggunakan kurikulum di kelas
362- Konten dirancang untuk aksesibilitas dan peningkatan kemampuan bertahap
363 
364### Filosofi Edukasi
365 
366- Pendekatan pembelajaran berbasis proyek
367- Pemeriksaan pengetahuan yang sering (kuis)
368- Latihan coding langsung
369- Contoh penerapan dunia nyata
370- Fokus pada dasar sebelum framework
371 
372### Pemeliharaan Repositori
373 
374- Komunitas pembelajar dan kontributor yang aktif
375- Pembaruan rutin pada dependensi dan konten
376- Masalah dan diskusi dipantau oleh pemelihara
377- Update terjemahan otomatis melalui GitHub Actions
378 
379### Sumber Daya Terkait
380 
381- [Modul Microsoft Learn](https://docs.microsoft.com/learn/)
382- [Sumber Daya Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) direkomendasikan untuk pembelajar
384- Kursus tambahan: Generative AI, Data Science, ML, kurikulum IoT tersedia
385 
386### Bekerja dengan Proyek Spesifik
387 
388Untuk instruksi rinci proyek individual, lihat README di:
389- `quiz-app/README.md` - aplikasi kuis Vue 3
390- `7-bank-project/README.md` - aplikasi perbankan dengan autentikasi
391- `5-browser-extension/README.md` - pengembangan ekstensi browser
392- `6-space-game/README.md` - pengembangan game berbasis canvas
393- `9-chat-project/README.md` - proyek asisten chat AI
394 
395### Struktur Monorepo
396 
397Meski bukan monorepo tradisional, repositori ini berisi beberapa proyek independen:
398- Setiap pelajaran bersifat mandiri
399- Proyek tidak berbagi dependensi
400- Kerjakan proyek individual tanpa memengaruhi proyek lain
401- Clone seluruh repo untuk pengalaman kurikulum lengkap
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Penafian**:  
407Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berusaha untuk akurasi, harap diingat bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi yang penting, disarankan untuk menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang salah yang timbul dari penggunaan terjemahan ini.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->