AGENTS.md

1# AGENTS.md
2 
3## Project Overview
4 
5Ito ay isang edukasyonal na repositoryo ng kurikulum para sa pagtuturo ng mga pangunahing kaalaman sa web development sa mga nagsisimula. Ang kurikulum ay isang komprehensibong 12-linggong kurso na binuo ng Microsoft Cloud Advocates, na nagtatampok ng 24 na hands-on na aralin na sumasaklaw sa JavaScript, CSS, at HTML.
6 
7### Key Components
8 
9- **Nilalaman Pang-edukasyon**: 24 na istrukturadong aralin na inayos sa mga proyekto bilang mga modulo
10- **Praktikal na Mga Proyekto**: Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor, at AI Chat Assistant
11- **Interaktibong Mga Quiz**: 48 na quiz na may tig-3 tanong bawat isa (pagsusulit bago/pagkatapos ng aralin)
12- **Suporta sa Maraming Wika**: Awtomatikong pagsasalin para sa 50+ na wika gamit ang GitHub Actions
13- **Mga Teknolohiya**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (para sa mga AI na proyekto)
14 
15### Architecture
16 
17- Edukasyonal na repositoryo na may istruktura batay sa mga aralin
18- Ang bawat folder ng aralin ay naglalaman ng README, mga halimbawa ng code, at mga solusyon
19- Mga standalone na proyekto sa hiwalay na mga direktoryo (quiz-app, iba't ibang mga proyekto sa aralin)
20- Sistema ng pagsasalin gamit ang GitHub Actions (co-op-translator)
21- Dokumentasyon na ibinibigay sa pamamagitan ng Docsify at available bilang PDF
22 
23## Setup Commands
24 
25Ang repositoryong ito ay pangunahing para sa konsumpsyon ng edukasyonal na nilalaman. Para sa pagtatrabaho sa mga partikular na proyekto:
26 
27### Main Repository Setup
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Quiz App Setup (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Simulan ang development server
40npm run build      # I-build para sa produksyon
41npm run lint       # Patakbuhin ang ESLint
42```
43 
44### Bank Project API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Simulan ang API server
50npm run lint       # Patakbuhin ang ESLint
51npm run format     # I-format gamit ang Prettier
52```
53 
54### Browser Extension Projects
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Sundin ang mga tagubilin sa pag-load ng extension na partikular sa browser
60```
61 
62### Space Game Projects
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Buksan ang index.html sa browser o gamitin ang Live Server
68```
69 
70### Chat Project (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Itakda ang GITHUB_TOKEN na variable ng kapaligiran
76python api.py
77```
78 
79## Development Workflow
80 
81### Para sa mga Contributor ng Nilalaman
82 
831. **I-fork ang repositoryo** sa iyong GitHub account
842. **I-clone ang iyong fork** nang lokal
853. **Gumawa ng bagong sanga** para sa iyong mga pagbabago
864. Gawin ang mga pagbabago sa nilalaman ng aralin o mga halimbawa ng code
875. Subukan ang anumang pagbabago sa code sa mga kaukulang direktoryo ng proyekto
886. Mag-submit ng pull requests alinsunod sa mga gabay sa kontribusyon
89 
90### Para sa mga Nag-aaral
91 
921. I-fork o i-clone ang repositoryo
932. Mag-navigate sa mga direktoryo ng aralin sunod-sunod
943. Basahin ang mga README file para sa bawat aralin
954. Kumpletuhin ang mga pre-lesson quizzes sa https://ff-quizzes.netlify.app/web/
965. Trabahuhin ang mga halimbawa ng code sa mga folder ng aralin
976. Kumpletuhin ang mga takdang-aralin at hamon
987. Sagutan ang mga post-lesson quizzes
99 
100### Live Development
101 
102- **Dokumentasyon**: Patakbuhin ang `docsify serve` sa root (port 3000)
103- **Quiz App**: Patakbuhin ang `npm run dev` sa folder ng quiz-app
104- **Mga Proyekto**: Gamitin ang VS Code Live Server extension para sa mga HTML na proyekto
105- **API Projects**: Patakbuhin ang `npm start` sa mga kaukulang API na direktoryo
106 
107## Testing Instructions
108 
109### Quiz App Testing
110 
111```bash
112cd quiz-app
113npm run lint       # Suriin kung may mga isyu sa istilo ng kodigo
114npm run build      # Tiyakin na matagumpay ang pagbuo
115```
116 
117### Bank API Testing
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Suriin ang mga isyu sa estilo ng code
122node server.js     # Tiyaking nagsisimula ang server nang walang mga error
123```
124 
125### Pangkalahatang Paraan ng Pagsusuri
126 
127- Ito ay isang edukasyonal na repositoryo na walang komprehensibong automated tests
128- Ang manual na pagsusuri ay nakatuon sa:
129  - Hindi nagkakaroon ng error ang mga halimbawa ng code kapag pinatakbo
130  - Gumagana nang maayos ang mga links sa dokumentasyon
131  - Matagumpay ang pagbuo ng mga proyekto
132  - Sumusunod ang mga halimbawa sa pinakamahusay na mga kasanayan
133 
134### Mga Pre-submission Checks
135 
136- Patakbuhin ang `npm run lint` sa mga direktoryong may package.json
137- Tiyakin na wasto ang mga markdown links
138- Subukan ang mga halimbawa ng code sa browser o Node.js
139- Suriin na ang mga pagsasalin ay nananatiling maayos ang istruktura
140 
141## Code Style Guidelines
142 
143### JavaScript
144 
145- Gumamit ng makabagong ES6+ na syntax
146- Sundin ang mga standard ESLint na konfigurasyon na ibinigay sa mga proyekto
147- Gumamit ng makabuluhang mga pangalan ng variable at function para sa kalinawan sa edukasyon
148- Magdagdag ng mga paliwanag na komentaryo tungkol sa mga konsepto para sa mga nag-aaral
149- I-format gamit ang Prettier kung saan naka-configure
150 
151### HTML/CSS
152 
153- Semantic HTML5 elements
154- Mga prinsipyo ng responsive design
155- Malinaw na conventions sa pagbibigay ng pangalan sa mga klase
156- Mga komentaryo na nagpapaliwanag ng mga teknik sa CSS para sa mga nag-aaral
157 
158### Python
159 
160- Mga patnubay sa estilo ayon sa PEP 8
161- Malinaw, pang-edukasyonal na mga halimbawa ng code
162- Mga type hint kung nakakatulong sa pag-aaral
163 
164### Markdown Documentation
165 
166- Malinaw na hierarchy ng mga heading
167- Mga code block na may pagspecify ng wika
168- Mga link sa karagdagang mga mapagkukunan
169- Mga screenshot at larawan sa mga `images/` na mga direktoryo
170- Alt text para sa mga larawan para sa accessibility
171 
172### File Organization
173 
174- Ang mga aralin ay may sunud-sunod na bilang (1-getting-started-lessons, 2-js-basics, atbp.)
175- Ang bawat proyekto ay may `solution/` at madalas `start/` o `your-work/` na mga direktoryo
176- Ang mga larawan ay naka-imbak sa mga lesson-specific na `images/` folder
177- Mga pagsasalin sa istrukturang `translations/{language-code}/`
178 
179## Build and Deployment
180 
181### Quiz App Deployment (Azure Static Web Apps)
182 
183Ang quiz-app ay naka-configure para sa Azure Static Web Apps deployment:
184 
185```bash
186cd quiz-app
187npm run build      # Lumilikha ng dist/ folder
188# Nagde-deploy gamit ang GitHub Actions workflow kapag may push sa main
189```
190 
191Azure Static Web Apps na konfigurasyon:
192- **App location**: `/quiz-app`
193- **Output location**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Documentation PDF Generation
197 
198```bash
199npm install                    # I-install ang docsify-to-pdf
200npm run convert               # Gumawa ng PDF mula sa docs
201```
202 
203### Docsify Documentation
204 
205```bash
206npm install -g docsify-cli    # I-install ang Docsify nang globally
207docsify serve                 # I-serve sa localhost:3000
208```
209 
210### Mga Build na Nakatuon sa Proyekto
211 
212Ang bawat direktoryo ng proyekto ay maaaring may sariling proseso ng build:
213- Vue projects: `npm run build` na lumilikha ng mga production bundles
214- Static projects: Walang build step, direktang pag-serbisyo ng mga file
215 
216## Pull Request Guidelines
217 
218### Format ng Pamagat
219 
220Gumamit ng malinaw, deskriptibong mga pamagat na nagpapakita ng bahagi ng pagbabago:
221- `[Quiz-app] Add new quiz for lesson X`
222- `[Lesson-3] Fix typo in terrarium project`
223- `[Translation] Add Spanish translation for lesson 5`
224- `[Docs] Update setup instructions`
225 
226### Mga Kinakailangang Pag-check
227 
228Bago magsumite ng PR:
229 
2301. **Kalidad ng Code**:
231   - Patakbuhin ang `npm run lint` sa mga apektadong proyekto
232   - Ayusin ang lahat ng linting error at babala
233 
2342. **Pag-verify ng Build**:
235   - Patakbuhin ang `npm run build` kung kinakailangan
236   - Siguraduhing walang error sa build
237 
2383. **Pag-validate ng Link**:
239   - Subukan ang lahat ng markdown link
240   - Siguraduhing gumagana ang mga reference ng larawan
241 
2424. **Pagsusuri ng Nilalaman**:
243   - Proofread para sa baybay at gramatika
244   - Siguraduhing tama at edukasyonal ang mga halimbawa ng code
245   - I-verify ang mga pagsasalin ay nananatili ang orihinal na kahulugan
246 
247### Mga Kinakailangan sa Kontribusyon
248 
249- Sumang-ayon sa Microsoft CLA (automated check sa unang PR)
250- Sundin ang [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Tumingin sa [CONTRIBUTING.md](./CONTRIBUTING.md) para sa mga detalyadong gabay
252- Banggitin ang mga numero ng isyu sa paglalarawan ng PR kung angkop
253 
254### Proseso ng Review
255 
256- Ang mga PR ay sinusuri ng mga maintainer at komunidad
257- Pinapahalagahan ang kalinawan sa edukasyon
258- Dapat sundin ng mga halimbawa ng code ang kasalukuyang best practices
259- Sinusuri ang mga pagsasalin para sa katumpakan at angkop na kultura
260 
261## Translation System
262 
263### Automated Translation
264 
265- Gumagamit ng GitHub Actions na may co-op-translator workflow
266- Nagsasalin sa 50+ na wika nang awtomatiko
267- Mga source file sa mga pangunahing direktoryo
268- Mga naisaling file sa `translations/{language-code}/` na mga direktoryo
269 
270### Pagdaragdag ng Manual na Pagpapabuti sa Pagsasalin
271 
2721. Hanapin ang file sa `translations/{language-code}/`
2732. Gawin ang mga pagpapabuti nang pinananatili ang istruktura
2743. Siguraduhing nananatiling gumagana ang mga halimbawa ng code
2754. Subukan ang anumang lokal na nilalamang quiz
276 
277### Metadata ng Pagsasalin
278 
279Ang mga naisaling file ay may kasamang metadata header:
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 and Troubleshooting
293 
294### Mga Karaniwang Isyu
295 
296**Hindi nagsisimula ang quiz app**:
297- Suriin ang bersyon ng Node.js (inirekomenda v14+)
298- Burahin ang `node_modules` at `package-lock.json`, patakbuhin muli ang `npm install`
299- Suriin kung may conflict sa port (default: Vite gumagamit ng port 5173)
300 
301**Hindi nagsisimula ang API server**:
302- Tiyakin ang bersyon ng Node.js ay sapat (node >=10)
303- Suriin kung ginagamit na ng iba ang port
304- Siguraduhing naka-install lahat ng dependencies gamit ang `npm install`
305 
306**Hindi naglo-load ang browser extension**:
307- Siguraduhing tama ang format ng manifest.json
308- Tingnan ang browser console para sa mga error
309- Sundin ang mga instruksyon sa pag-install ng extension para sa partikular na browser
310 
311**Mga isyu sa Python chat project**:
312- Siguraduhing naka-install ang OpenAI package: `pip install openai`
313- Tiyakin na nakaset ang GITHUB_TOKEN environment variable
314- Suriin ang mga permiso sa access ng GitHub Models
315 
316**Hindi nagseserbisyo ang Docsify ng docs**:
317- I-install ang docsify-cli globally: `npm install -g docsify-cli`
318- Patakbuhin mula sa root directory ng repositoryo
319- Siguraduhing may `docs/_sidebar.md`
320 
321### Mga Tip para sa Development Environment
322 
323- Gumamit ng VS Code kasama ang Live Server extension para sa mga HTML na proyekto
324- Mag-install ng ESLint at Prettier extensions para sa konsistenteng pag-format
325- Gamitin ang browser DevTools para i-debug ang JavaScript
326- Para sa mga Vue na proyekto, mag-install ng Vue DevTools browser extension
327 
328### Mga Pagsasaalang-alang sa Performance
329 
330- Malaki ang bilang ng naisaling mga file (50+ na wika) kaya malaki ang buong clone
331- Gumamit ng shallow clone kung nilalaman lang ang kanilang tinatrabaho: `git clone --depth 1`
332- I-exclude ang mga pagsasalin sa mga paghahanap kapag nagtatrabaho sa English na nilalaman
333- Maaaring mabagal ang build processes sa unang takbo (npm install, Vite build)
334 
335## Security Considerations
336 
337### Mga Environment Variable
338 
339- Huwag kailanman i-commit ang API keys sa repositoryo
340- Gumamit ng `.env` files (nasa `.gitignore` na)
341- I-dokumento ang kinakailangang environment variables sa mga README ng proyekto
342 
343### Python Projects
344 
345- Gumamit ng virtual environments: `python -m venv venv`
346- Panatilihing updated ang mga dependencies
347- Dapat may minimal na permiso lamang ang mga GitHub token
348 
349### GitHub Models Access
350 
351- Kinakailangan ang Personal Access Tokens (PAT) para sa GitHub Models
352- Itago ang mga token bilang environment variables
353- Huwag kailanman i-commit ang mga token o kredensyal
354 
355## Additional Notes
356 
357### Target Audience
358 
359- Mga ganap na nagsisimula sa web development
360- Mga estudyante at self-learners
361- Mga guro na gumagamit ng kurikulum sa mga silid-aralan
362- Ang nilalaman ay dinisenyo para sa accessibility at unti-unting pagbuo ng kakayahan
363 
364### Educational Philosophy
365 
366- Pagsasanay sa pag-aaral batay sa proyekto
367- Madalas na pagsusuri sa kaalaman (mga quiz)
368- Hands-on na coding exercises
369- Mga halimbawa ng aplikasyon sa tunay na mundo
370- Pagtuon sa mga pundasyon bago ang mga framework
371 
372### Repository Maintenance
373 
374- Aktibong komunidad ng mga nag-aaral at contributor
375- Regular na pag-update ng dependencies at nilalaman
376- Sina-subsaybayan ang mga isyu at talakayan ng mga maintainer
377- Awtomatikong pag-update ng pagsasalin gamit ang GitHub Actions
378 
379### Related Resources
380 
381- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
382- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
383- Inirerekomenda ang [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) para sa mga nag-aaral
384- Karagdagang mga kurso: Generative AI, Data Science, ML, IoT curricula ang available
385 
386### Pagtatrabaho sa Partikular na Mga Proyekto
387 
388Para sa detalyadong mga instruksyon sa mga indibidwal na proyekto, tingnan ang mga README file sa:
389- `quiz-app/README.md` - Vue 3 quiz application
390- `7-bank-project/README.md` - Banking application na may authentication
391- `5-browser-extension/README.md` - Pag-develop ng browser extension
392- `6-space-game/README.md` - Pag-develop ng game gamit ang canvas
393- `9-chat-project/README.md` - AI chat assistant project
394 
395### Monorepo Structure
396 
397Bagamat hindi tradisyunal na monorepo, ang repositoryong ito ay naglalaman ng maraming independiyenteng proyekto:
398- Ang bawat aralin ay nakahiwalay
399- Hindi nagbabahagi ng dependencies ang mga proyekto
400- Puwedeng magtrabaho sa bawat proyekto nang hindi naaapektuhan ang iba
401- I-clone ang buong repo para sa buong karanasan ng kurikulum
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Paunawa**:  
407Ang dokumentong ito ay isinalin gamit ang AI translation service na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagaman nagsusumikap kami para sa katuparan, pakatandaan na ang mga awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mga mahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot para sa anumang hindi pagkakaunawaan o maling interpretasyon na nagmumula sa paggamit ng pagsasaling ito.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->