AGENTS.md

1# AGENTS.md
2 
3## Muhtasari wa Mradi
4 
5Huu ni hazina ya mtaala wa elimu kwa ajili ya kufundisha misingi ya maendeleo ya wavuti kwa wanaoanza. Mtaala ni kozi kamili ya wiki 12 iliyotengenezwa na Microsoft Cloud Advocates, ikiwa na masomo 24 ya vitendo yanayohusu JavaScript, CSS, na HTML.
6 
7### Vipengele Muhimu
8 
9- **Yaliyomo ya Elimu**: Masomo 24 yaliyopangwa kwa muundo wa moduli za miradi
10- **Miradi ya Vitendo**: Terrarium, Mchezo wa Kuandika, Upanuzi wa Kivinjari, Mchezo wa Anga, Programu ya Benki, Mhariri wa Msimbo, na Msaidizi wa AI wa Mazungumzo
11- **Maswali Shindani Ya Kihusianisho**: Maswali 48 kila moja ikiwa na maswali 3 (majaribio kabla/baada ya somo)
12- **Msaada wa Lugha Nyingi**: Tafsiri za moja kwa moja za lugha zaidi ya 50 kupitia GitHub Actions
13- **Teknolojia**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (kwa miradi ya AI)
14 
15### Miundo-Mbinu
16 
17- Hazina ya elimu yenye muundo wa masomo
18- Kila folda ya somo ina README, mifano ya msimbo, na suluhisho
19- Miradi huru katika saraka tofauti (quiz-app, miradi mbalimbali ya masomo)
20- Mfumo wa tafsiri ukitumia GitHub Actions (co-op-translator)
21- Nyaraka zinatolewa kupitia Docsify na zinapatikana kama PDF
22 
23## Amri za Kuanzisha
24 
25Hazina hii ni hasa kwa kutumia yaliyomo ya elimu. Kwa kufanya kazi na miradi maalum:
26 
27### Kuanzisha Hazina Kuu
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Kuanzisha Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Anzisha seva ya maendeleo
40npm run build      # Tengeneza kwa ajili ya uzalishaji
41npm run lint       # Endesha ESLint
42```
43 
44### API ya Mradi wa Benki (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Anzisha seva ya API
50npm run lint       # Endesha ESLint
51npm run format     # Pangilia kwa Prettier
52```
53 
54### Miradi ya Upanuzi wa Kivinjari
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Fuata maagizo ya kupakia upanuzi maalum kwa kivinjari
60```
61 
62### Miradi ya Mchezo wa Anga
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Fungua index.html katika kivinjari au tumia Live Server
68```
69 
70### Mradi wa Mazungumzo (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Weka kigezo cha mazingira cha GITHUB_TOKEN
76python api.py
77```
78 
79## Mtiririko wa Maendeleo
80 
81### Kwa Wasaidizi wa Yaliyomo
82 
831. **Fungua hazina kwa fork** kwa akaunti yako ya GitHub
842. **Nakili fork yako** mahali hapo ndani
853. **Tengeneza tawi jipya** kwa mabadiliko yako
864. Fanya mabadiliko kwenye yaliyomo ya masomo au mifano ya msimbo
875. Jaribu mabadiliko yoyote ya msimbo katika saraka za miradi husika
886. Wasilisha rufaa za kuchukua mabadiliko kuzingatia miongozo ya mchango
89 
90### Kwa Wanafunzi
91 
921. Funga au nakili hazina
932. Elekea kwenye saraka za masomo kwa mpangilio
943. Soma faili za README kwa kila somo
954. Maliza maswali ya kabla ya somo huko https://ff-quizzes.netlify.app/web/
965. Fanyia kazi mifano ya msimbo katika folda za masomo
976. Maliza kazi za nyumbani na changamoto
987. Fanya maswali ya baada ya somo
99 
100### Maendeleo Hai
101 
102- **Nyaraka**: Endesha `docsify serve` kwenye saraka ya juu (bandari 3000)
103- **Quiz App**: Endesha `npm run dev` kwenye folda ya quiz-app
104- **Miradi**: Tumia upanuzi wa VS Code Live Server kwa miradi ya HTML
105- **Miradi ya API**: Endesha `npm start` katika saraka husika za API
106 
107## Maelekezo ya Kupima
108 
109### Kupima Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Angalia kwa matatizo ya mtindo wa msimbo
114npm run build      # Thibitisha ujenzi unafanikiwa
115```
116 
117### Kupima API ya Benki
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Angalia kwa masuala ya mtindo wa msimbo
122node server.js     # Thibitisha seva inaanza bila makosa
123```
124 
125### Mbinu ya Kupima kwa Ujumla
126 
127- Hii ni hazina ya elimu isiyo na majaribio ya moja kwa moja ya kina
128- Kupima kwa mikono kunalenga:
129  - Mifano ya msimbo inakimbia bila makosa
130  - Viungo vya nyaraka vinafanya kazi kikamilifu
131  - Miradi kujengwa kikamilifu bila hitilafu
132  - Mifano inafuata mbinu bora
133 
134### Ukaguzi Kabla ya Kuwasilisha
135 
136- Endesha `npm run lint` katika saraka zilizo na package.json
137- Hakiki viungo vya markdown vipate usahihi
138- Jaribu mifano ya msimbo kwenye kivinjari au Node.js
139- Hakikisha tafsiri zinahifadhi muundo sahihi
140 
141## Miongozo ya Mtindo wa Msimbo
142 
143### JavaScript
144 
145- Tumia lugha ya kisasa ya ES6+
146- Fuata mipangilio ya kawaida ya ESLint iliyopo katika miradi
147- Tumia majina yenye maana kwa mabadiliko na kazi kwa ajili ya ufafanuzi wa elimu
148- Ongeza maelezo kuelezea dhana kwa wanafunzi
149- Tengeneza kwa kutumia Prettier pale panapopangwa
150 
151### HTML/CSS
152 
153- Vipengele vya semantic vya HTML5
154- Kanuni za muundo wa kujibadilisha (responsive)
155- Viwango vya uandishi vya darasa wazi
156- Maelezo kuelezea mbinu za CSS kwa wanafunzi
157 
158### Python
159 
160- Miongozo ya mtindo ya PEP 8
161- Mifano ya msimbo wazi, ya elimu
162- Vidokezo vya aina inapobidi kwa kujifunza
163 
164### Nyaraka za Markdown
165 
166- Muundo wa vichwa vya habari kwa uwazi
167- Mifumo ya msimbo yenye lugha maalum
168- Viungo kwenye rasilimali za ziada
169- Picha na picha ndogo katika saraka za `images/`
170- Maandishi ya alt ya picha kwa upatikanaji
171 
172### Mpangilio wa Faili
173 
174- Masomo yamenumberwa kwa mfuatano (1-getting-started-lessons, 2-js-basics, nk)
175- Kila mradi una saraka za `solution/` na mara nyingi `start/` au `your-work/`
176- Picha zimehifadhiwa katika saraka maalum za masomo `images/`
177- Tafsiri ziko katika muundo wa `translations/{language-code}/`
178 
179## Ujenzi na Uenezaji
180 
181### Uenezaji wa Quiz App (Azure Static Web Apps)
182 
183Quiz-app imewekwa kwa ajili ya uenezaji wa Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Inaunda folda ya dist/
188# Inaendesha kupitia mtiririko wa kazi wa GitHub Actions wakati wa kusukuma kwenye main
189```
190 
191Mipangilio ya Azure Static Web Apps:
192- **Eneo la app**: `/quiz-app`
193- **Eneo la matokeo**: `dist`
194- **Mtiririko wa kazi**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Uzalishaji wa PDF wa Nyaraka
197 
198```bash
199npm install                    # Sakinisha docsify-to-pdf
200npm run convert               # Tengeneza PDF kutoka kwa docs
201```
202 
203### Nyaraka za Docsify
204 
205```bash
206npm install -g docsify-cli    # Sakinisha Docsify kote duniani
207docsify serve                 # Tumikia kwenye localhost:3000
208```
209 
210### Ujenzi wa Miradi Maalum
211 
212Kila saraka ya mradi inaweza kuwa na mchakato wake wa ujenzi:
213- Miradi ya Vue: `npm run build` huunda vifurushi vya uzalishaji
214- Miradi isiyohitaji ujenzi: Hakuna hatua ya ujenzi, hudumisha faili moja kwa moja
215 
216## Miongozo ya Rufaa za Kuchukua Mabadiliko (Pull Requests)
217 
218### Muundo wa Kichwa
219 
220Tumia vichwa wazi, vinavyoelezea maeneo ya mabadiliko:
221- `[Quiz-app] Ongeza mtihani mpya kwa somo X`
222- `[Lesson-3] Rekebisha tahajia katika mradi wa terrarium`
223- `[Translation] Ongeza tafsiri ya Kihispania kwa somo 5`
224- `[Docs] Sasisha maelekezo ya kuanzisha`
225 
226### Vyakati Vinavyohitajika
227 
228Kabla ya kuwasilisha PR:
229 
2301. **Ubora wa Msimbo**:
231   - Endesha `npm run lint` katika saraka zilizoathirika
232   - Rekebisha makosa na onyo zote za lint
233 
2342. **Uhakiki wa Ujenzi**:
235   - Endesha `npm run build` inapohitajika
236   - Hakikisha hakuna makosa ya ujenzi
237 
2383. **Uhakiki wa Viungo**:
239   - Jaribu viungo vyote vya markdown
240   - Thibitisha marejeo ya picha zinafanya kazi
241 
2424. **Ukaguzi wa Yaliyomo**:
243   - Soma kwa makini kwa makosa ya tahajia na sarufi
244   - Hakikisha mifano ya msimbo ni sahihi na ya kielimu
245   - Hakikisha tafsiri zinahifadhi maana asilia
246 
247### Masharti ya Michango
248 
249- Kubali Microsoft CLA (ukaguzi wa moja kwa moja kwa PR ya kwanza)
250- Fuata [Sheria za Maadili za Chanzo Huria za Microsoft](https://opensource.microsoft.com/codeofconduct/)
251- Angalia [CONTRIBUTING.md](./CONTRIBUTING.md) kwa miongozo ya kina
252- Taja nambari za masuala katika maelezo ya PR inapowezekana
253 
254### Mchakato wa Ukaguzi
255 
256- PR hurejelewa na waendelezaji na jamii
257- Uwazi wa elimu unaangaziwa
258- Mifano ya msimbo inapaswa kufuata mbinu bora za sasa
259- Tafsiri hurejelewa kwa usahihi na utamaduni unaofaa
260 
261## Mfumo wa Tafsiri
262 
263### Tafsiri ya Moja kwa Moja (Automated)
264 
265- Inatumia GitHub Actions na mtiririko wa co-op-translator
266- Inatafsiri hadi lugha zaidi ya 50 moja kwa moja
267- Faili za chanzo ziko katika saraka kuu
268- Faili za tafsiri ziko katika saraka za `translations/{language-code}/`
269 
270### Kuongeza Maboresho ya Tafsiri Kwa Mkono
271 
2721. Tafuta faili katika `translations/{language-code}/`
2732. Fanya maboresho huku ukihifadhi muundo
2743. Hakikisha mifano ya msimbo inabaki kutumika
2754. Jaribu yaliyomo ya mitihani iliyotafsiriwa
276 
277### Metadata ya Tafsiri
278 
279Faili za tafsiri zina kichwa cha 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## Kurekebisha na Kutatua Matatizo
293 
294### Changamoto Zaidi Zaidi
295 
296**App ya Quiz haianzi**:
297- Hakiki toleo la Node.js (inashauriwa v14+)
298- Futa `node_modules` na `package-lock.json`, endesha tena `npm install`
299- Angalia migongano ya bandari (kawaida: Vite hutumia bandari 5173)
300 
301**Server ya API haianzi**:
302- Hakiki toleo la Node.js linakidhi (node >=10)
303- Angalia kama bandari tayari inatumika
304- Hakikisha utegemezi wote umetolewa kwa `npm install`
305 
306**Upanuzi wa kivinjari hauanziki**:
307- Hakiki manifest.json imepandishwa vema
308- Angalia console ya kivinjari kwa makosa
309- Fuata maelekezo ya usanidi wa upanuzi wa kivinjari
310 
311**Matatizo ya Mradi wa Mazungumzo wa Python**:
312- Hakikisha kifurushi cha OpenAI kimesakinishwa: `pip install openai`
313- Hakiki kuwa mabadiliko ya mazingira ya GITHUB_TOKEN yamewekwa
314- Hakiki vibali vya ufikiaji kwa GitHub Models
315 
316**Docsify haisikilizi nyaraka**:
317- Sakinisha docsify-cli ulimwenguni: `npm install -g docsify-cli`
318- Endesha kutoka saraka kuu ya hazina
319- Hakiki `docs/_sidebar.md` ipo
320 
321### Vidokezo vya Mazingira ya Maendeleo
322 
323- Tumia VS Code na upanuzi wa Live Server kwa miradi ya HTML
324- Sakinisha upanuzi za ESLint na Prettier kwa mtindo thabiti
325- Tumia DevTools wa kivinjari kwa kupata na kutatua makosa ya JavaScript
326- Kwa miradi ya Vue, sakinisha upanuzi wa Vue DevTools kivinjari
327 
328### Mambo ya Kujali Kuhusu Utendaji
329 
330- Idadi kubwa ya faili za tafsiri (za lugha 50+) huongeza ukubwa wa nakala kamili
331- Tumia nakala ya chini (shallow) ikiwa unafanya kazi tu kwa yaliyomo: `git clone --depth 1`
332- Epuka tafutiza za tafsiri wakati unafanya kazi na yaliyomo ya Kiingereza
333- Mienendo ya ujenzi inaweza kuwa polepole mwanzoni (npm install, ujenzi wa Vite)
334 
335## Masuala ya Usalama
336 
337### Mabadiliko ya Mazingira
338 
339- Funguo za API hazipaswi kuwekwa moja kwa moja katika hazina
340- Tumia faili za `.env` (zipo katika `.gitignore`)
341- Elezea mabadiliko ya mazingira yanayohitajika katika README za miradi
342 
343### Miradi ya Python
344 
345- Tumia mazingira ya pekee: `python -m venv venv`
346- Sasisha utegemezi mara kwa mara
347- Tokeni za GitHub zinapaswa kuwa na vibali vidogo vinavyotakiwa tu
348 
349### Ufikiaji wa GitHub Models
350 
351- Mipangilio ya Ufikiaji wa Kibinafsi (PAT) inahitajika kwa GitHub Models
352- Tokeni ziwe katika mabadiliko ya mazingira
353- Kamwe usiweka tokeni au nyaraka katika hazina
354 
355## Vidokezo Zaidi
356 
357### Hadhira Lengwa
358 
359- Wananchi wapya kabisa katika maendeleo ya wavuti
360- Wanafunzi na waelimishaji wa kujifunza peke yao
361- Walimu wanaotumia mtaala darasani
362- Yaliyomo yamebuniwa kwa kupatikana na kukuza hatua kwa hatua ujuzi
363 
364### Falsafa ya Elimu
365 
366- Mbinu ya kujifunza kwa miradi
367- Ukaguzi wa mara kwa mara wa maarifa (maswali)
368- Mazoezi ya kuandika msimbo kwa vitendo
369- Mifano ya matumizi halisi ya dunia ya kweli
370- Kuzingatia misingi kabla ya mifumo ngumu
371 
372### Matengenezo ya Hazina
373 
374- Jamii hai ya wanafunzi na wasaidizi
375- Sasisho za mara kwa mara za utegemezi na yaliyomo
376- Masuala na majadiliano yanatazamwa na watunzaji
377- Sasisho za tafsiri zimepangwa moja kwa moja kupitia GitHub Actions
378 
379### Rasilimali Zinazohusiana
380 
381- [Moduli za Microsoft Learn](https://docs.microsoft.com/learn/)
382- [Rasilimali za Kitovu cha Mwanafunzi](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) inashauriwa kwa wanafunzi
384- Kozi zingine: AI ya kuzalisha, Sayansi ya Data, ML, na mtaala wa IoT zinapatikana
385 
386### Kufanya kazi na Miradi Mahususi
387 
388Kwa maelekezo ya kina juu ya miradi binafsi, rejea faili za README katika:
389- `quiz-app/README.md` - Programu ya mtihani ya Vue 3
390- `7-bank-project/README.md` - Programu ya benki yenye uthibitishaji
391- `5-browser-extension/README.md` - Maendeleo ya upanuzi wa kivinjari
392- `6-space-game/README.md` - Maendeleo ya mchezo wa Canvas
393- `9-chat-project/README.md` - Mradi wa msaidizi wa mazungumzo wa AI
394 
395### Muundo wa Monorepo
396 
397Ingawa sio monorepo ya kawaida, hazina hii ina miradi huru mingi:
398- Kila somo limejitegemea
399- Miradi haishiriki utegemezi
400- Fanya kazi kwenye miradi binafsi bila kuathiri mingine
401- Nakili hazina nzima kwa uzoefu kamili wa mtaala
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Kinyang'anyiro**:
407Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Wakati tunajitahidi kwa usahihi, tafadhali fahamu kwamba tafsiri za kiotomati zinaweza kuwa na makosa au upotoshaji. Hati ya asili katika lugha yake ya asili inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya mtaalamu wa binadamu inapendekezwa. Hatubeba jukumu la kutokea kwa kutoelewana au tafsiri potofu kutokana na matumizi ya tafsiri hii.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->