12 KiB

Raw Permalink Blame History

AGENTS.md

Gambaran Proyek

Ini adalah repositori kurikulum edukatif untuk mengajarkan dasar-dasar pengembangan web kepada pemula. Kurikulum ini adalah kursus komprehensif selama 12 minggu yang dikembangkan oleh Microsoft Cloud Advocates, menampilkan 24 pelajaran langsung yang mencakup JavaScript, CSS, dan HTML.

Komponen Utama

Konten Edukasi: 24 pelajaran terstruktur yang diorganisir dalam modul berbasis proyek
Proyek Praktis: Terrarium, Permainan Mengetik, Ekstensi Browser, Permainan Luar Angkasa, Aplikasi Perbankan, Editor Kode, dan Asisten Chat AI
Kuis Interaktif: 48 kuis dengan 3 pertanyaan masing-masing (evaluasi sebelum/sesudah pelajaran)
Dukungan Multibahasa: Terjemahan otomatis untuk lebih dari 50 bahasa melalui GitHub Actions
Teknologi: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (untuk proyek AI)

Arsitektur

Repositori edukasi dengan struktur berbasis pelajaran
Setiap folder pelajaran berisi README, contoh kode, dan solusi
Proyek mandiri dalam direktori terpisah (quiz-app, berbagai proyek pelajaran)
Sistem terjemahan menggunakan GitHub Actions (co-op-translator)
Dokumentasi disajikan via Docsify dan tersedia sebagai PDF

Perintah Setup

Repositori ini terutama untuk konsumsi konten edukasi. Untuk bekerja dengan proyek tertentu:

Setup Repositori Utama

git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

Setup Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Mulai server pengembangan
npm run build      # Bangun untuk produksi
npm run lint       # Jalankan ESLint

API Proyek Bank (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Mulai server API
npm run lint       # Jalankan ESLint
npm run format     # Format dengan Prettier

Proyek Ekstensi Browser

cd 5-browser-extension/solution
npm install
# Ikuti instruksi pemuatan ekstensi spesifik browser

Proyek Permainan Luar Angkasa

cd 6-space-game/solution
npm install
# Buka index.html di browser atau gunakan Live Server

Proyek Chat (Backend Python)

cd 9-chat-project/solution/backend/python
pip install openai
# Atur variabel lingkungan GITHUB_TOKEN
python api.py

Alur Kerja Pengembangan

Untuk Kontributor Konten

Fork repositori ke akun GitHub Anda
Clone fork Anda secara lokal
Buat branch baru untuk perubahan Anda
Lakukan perubahan pada konten pelajaran atau contoh kode
Uji perubahan kode di direktori proyek terkait
Ajukan pull request sesuai pedoman kontribusi

Untuk Pembelajar

Fork atau clone repositori
Navigasi ke direktori pelajaran secara berurutan
Baca file README untuk setiap pelajaran
Selesaikan kuis sebelum pelajaran di https://ff-quizzes.netlify.app/web/
Kerjakan contoh kode dalam folder pelajaran
Selesaikan tugas dan tantangan
Ikuti kuis setelah pelajaran

Pengembangan Langsung

Dokumentasi: Jalankan docsify serve di root (port 3000)
Quiz App: Jalankan npm run dev di direktori quiz-app
Proyek: Gunakan ekstensi VS Code Live Server untuk proyek HTML
Proyek API: Jalankan npm start di direktori API terkait

Instruksi Pengujian

Pengujian Quiz App

cd quiz-app
npm run lint       # Periksa masalah gaya kode
npm run build      # Verifikasi build berhasil

Pengujian Bank API

cd 7-bank-project/api
npm run lint       # Periksa masalah gaya kode
node server.js     # Verifikasi server mulai tanpa kesalahan

Pendekatan Pengujian Umum

Ini adalah repositori edukasi tanpa pengujian otomatis komprehensif
Pengujian manual fokus pada:
- Contoh kode berjalan tanpa error
- Tautan dalam dokumentasi berfungsi dengan benar
- Build proyek selesai dengan sukses
- Contoh mengikuti praktik terbaik

Pemeriksaan Pra-Pengajuan

Jalankan npm run lint di direktori yang memiliki package.json
Verifikasi tautan markdown valid
Uji contoh kode di browser atau Node.js
Periksa bahwa terjemahan menjaga struktur yang tepat

Pedoman Gaya Kode

JavaScript

Gunakan sintaks ES6+ modern
Ikuti konfigurasi ESLint standar yang disediakan dalam proyek
Gunakan nama variabel dan fungsi yang bermakna untuk kejelasan edukasi
Tambahkan komentar yang menjelaskan konsep untuk pembelajar
Format menggunakan Prettier jika dikonfigurasi

HTML/CSS

Elemen HTML5 semantik
Prinsip desain responsif
Konvensi penamaan kelas yang jelas
Komentar yang menjelaskan teknik CSS untuk pembelajar

Python

Pedoman gaya PEP 8
Contoh kode yang jelas dan edukatif
Petunjuk tipe jika membantu pembelajaran

Dokumentasi Markdown

Hirarki judul yang jelas
Blok kode dengan spesifikasi bahasa
Tautan ke sumber tambahan
Screenshot dan gambar dalam direktori images/
Teks alt untuk gambar demi aksesibilitas

Organisasi Berkas

Pelajaran dinomori secara berurutan (1-getting-started-lessons, 2-js-basics, dll.)
Setiap proyek memiliki direktori solution/ dan sering start/ atau your-work/
Gambar disimpan dalam folder images/ spesifik pelajaran
Terjemahan di struktur translations/{language-code}/

Build dan Deployment

Deployment Quiz App (Azure Static Web Apps)

quiz-app dikonfigurasi untuk deployment Azure Static Web Apps:

cd quiz-app
npm run build      # Membuat folder dist/
# Melakukan deploy melalui workflow GitHub Actions saat push ke main

Konfigurasi Azure Static Web Apps:

Lokasi aplikasi: /quiz-app
Lokasi output: dist
Workflow: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Generasi PDF Dokumentasi

npm install                    # Pasang docsify-to-pdf
npm run convert               # Hasilkan PDF dari docs

Dokumentasi Docsify

npm install -g docsify-cli    # Instal Docsify secara global
docsify serve                 # Layani di localhost:3000

Build Spesifik Proyek

Setiap direktori proyek mungkin memiliki proses build sendiri:

Proyek Vue: npm run build membuat bundel produksi
Proyek statis: Tidak ada langkah build, sajikan berkas langsung

Pedoman Pull Request

Format Judul

Gunakan judul jelas dan deskriptif yang menunjukkan area perubahan:

[Quiz-app] Tambah kuis baru untuk pelajaran X
[Lesson-3] Perbaiki typo di proyek terrarium
[Translation] Tambah terjemahan Spanyol untuk pelajaran 5
[Docs] Perbarui instruksi setup

Pemeriksaan yang Diperlukan

Sebelum mengirim PR:

Kualitas Kode:
- Jalankan npm run lint di direktori proyek yang terdampak
- Perbaiki semua kesalahan dan peringatan linting
Verifikasi Build:
- Jalankan npm run build jika relevan
- Pastikan tidak ada error build
Validasi Tautan:
- Uji semua tautan markdown
- Verifikasi referensi gambar berfungsi
Review Konten:
- Periksa ejaan dan tata bahasa
- Pastikan contoh kode benar dan edukatif
- Verifikasi terjemahan menjaga makna asli

Persyaratan Kontribusi

Setujui CLA Microsoft (cek otomatis pada PR pertama)
Ikuti Kode Etik Open Source Microsoft
Lihat CONTRIBUTING.md untuk panduan rinci
Referensikan nomor isu dalam deskripsi PR jika relevan

Proses Review

PR direview oleh pemelihara dan komunitas
Kejelasan edukasi diprioritaskan
Contoh kode harus mengikuti praktik terbaik saat ini
Terjemahan dicek keakuratan dan kesesuaian budaya

Sistem Terjemahan

Terjemahan Otomatis

Menggunakan GitHub Actions dengan workflow co-op-translator
Menerjemahkan ke lebih dari 50 bahasa secara otomatis
Berkas sumber di direktori utama
Berkas terjemahan di direktori translations/{language-code}/

Menambahkan Perbaikan Terjemahan Manual

Cari berkas di translations/{language-code}/
Lakukan perbaikan sambil mempertahankan struktur
Pastikan contoh kode tetap berfungsi
Uji konten kuis yang dilokalkan

Metadata Terjemahan

Berkas terjemahan mencakup header metadata:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

Debugging dan Pemecahan Masalah

Masalah Umum

Quiz app gagal mulai:

Periksa versi Node.js (disarankan v14+)
Hapus node_modules dan package-lock.json, jalankan npm install lagi
Cek konflik port (default: Vite menggunakan port 5173)

Server API tidak mau mulai:

Verifikasi versi Node.js memenuhi minimum (node >=10)
Cek apakah port sudah digunakan
Pastikan semua dependensi terpasang dengan npm install

Ekstensi browser tidak bisa dimuat:

Verifikasi manifest.json terformat dengan benar
Cek konsol browser untuk error
Ikuti instruksi pemasangan ekstensi spesifik browser

Masalah proyek chat Python:

Pastikan paket OpenAI terpasang: pip install openai
Verifikasi variabel lingkungan GITHUB_TOKEN sudah diset
Cek izin akses GitHub Models

Docsify tidak menyajikan dokumentasi:

Instal docsify-cli global: npm install -g docsify-cli
Jalankan dari root repositori
Pastikan docs/_sidebar.md ada

Tips Lingkungan Pengembangan

Gunakan VS Code dengan ekstensi Live Server untuk proyek HTML
Pasang ekstensi ESLint dan Prettier untuk format konsisten
Gunakan DevTools browser untuk debugging JavaScript
Untuk proyek Vue, pasang ekstensi Vue DevTools browser

Pertimbangan Performa

Jumlah berkas terjemahan besar (50+ bahasa) membuat klon penuh besar
Gunakan shallow clone jika hanya bekerja dengan konten: git clone --depth 1
Kecualikan terjemahan saat mencari konten bahasa Inggris
Proses build mungkin lambat pada jalankan pertama (npm install, build Vite)

Pertimbangan Keamanan

Variabel Lingkungan

Kunci API tidak boleh di-commit ke repositori
Gunakan berkas .env (sudah masuk .gitignore)
Dokumentasikan variabel lingkungan yang diperlukan di README proyek

Proyek Python

Gunakan virtual environment: python -m venv venv
Jaga dependensi tetap terbarukan
Token GitHub harus memiliki izin minimal yang diperlukan

Akses GitHub Models

Personal Access Tokens (PAT) diperlukan untuk GitHub Models
Simpan token sebagai variabel lingkungan
Jangan pernah commit token atau kredensial

Catatan Tambahan

Sasaran Audiens

Pemula lengkap dalam pengembangan web
Mahasiswa dan pembelajar mandiri
Guru yang menggunakan kurikulum di kelas
Konten dirancang untuk aksesibilitas dan peningkatan keterampilan bertahap

Filosofi Edukasi

Pendekatan pembelajaran berbasis proyek
Pemeriksaan pengetahuan yang sering (kuis)
Latihan coding langsung
Contoh aplikasi dunia nyata
Fokus pada dasar sebelum framework

Pemeliharaan Repositori

Komunitas aktif pembelajar dan kontributor
Pembaruan rutin pada dependensi dan konten
Masalah dan diskusi dipantau oleh pemelihara
Pembaruan terjemahan otomatis via GitHub Actions

Sumber Daya Terkait

Modul Microsoft Learn
Sumber daya Student Hub
GitHub Copilot direkomendasikan untuk pembelajar
Kursus tambahan: AI Generatif, Data Science, ML, kurikulum IoT tersedia

Bekerja dengan Proyek Spesifik

Untuk instruksi rinci proyek individual, lihat file README di:

quiz-app/README.md - aplikasi kuis Vue 3
7-bank-project/README.md - aplikasi perbankan dengan autentikasi
5-browser-extension/README.md - pengembangan ekstensi browser
6-space-game/README.md - pengembangan game berbasis canvas
9-chat-project/README.md - proyek asisten chat AI

Struktur Monorepo

Meskipun bukan monorepo tradisional, repositori ini berisi beberapa proyek independen:

Setiap pelajaran berdiri sendiri
Proyek tidak berbagi dependensi
Bisa bekerja pada proyek tunggal tanpa memengaruhi lainnya
Clone seluruh repositori untuk pengalaman kurikulum lengkap

Penafian:
Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI Co-op Translator. Meskipun kami berusaha mencapai akurasi, harap diingat bahwa terjemahan otomatis dapat mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang salah yang timbul dari penggunaan terjemahan ini.

12 KiB Raw Permalink Blame History