AGENTS.md

1# AGENTS.md
2 
3## परियोजना अवलोकन
4 
5यह शुरुआती लोगों को वेब विकास के मूल तत्व सिखाने के लिए एक शैक्षिक पाठ्यक्रम रिपॉजिटरी है। यह पाठ्यक्रम एक संपूर्ण 12-सप्ताह का कोर्स है जिसे Microsoft क्लाउड एडवोकेट्स द्वारा विकसित किया गया है, जिसमें JavaScript, CSS, और HTML को कवर करने वाले 24 व्यावहारिक पाठ होते हैं।
6 
7### प्रमुख घटक
8 
9- **शैक्षिक सामग्री**: परियोजना-आधारित मॉड्यूल में व्यवस्थित 24 संरचित पाठ
10- **व्यावहारिक परियोजनाएँ**: टेररियम, टाइपिंग गेम, ब्राउज़र एक्सटेंशन, स्पेस गेम, बैंकिंग ऐप, कोड संपादक, और एआई चैट असिस्टेंट
11- **इंटरएक्टिव क्विज़**: 48 क्विज़, प्रत्येक में 3 प्रश्न (पाठ से पहले और बाद में मूल्यांकन)
12- **बहु-भाषा समर्थन**: GitHub Actions के माध्यम से 50+ भाषाओं के लिए स्वचालित अनुवाद
13- **प्रौद्योगिकियाँ**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (एआई परियोजनाओं के लिए)
14 
15### वास्तुकला
16 
17- शैक्षिक रिपॉजिटरी जो पाठ-आधारित संरचना पर आधारित है
18- प्रत्येक पाठ फोल्डर में README, कोड उदाहरण, और समाधान हैं
19- स्वायत्त परियोजनाएँ अलग-अलग निर्देशिकाओं में (quiz-app, विभिन्न पाठ परियोजनाएँ)
20- GitHub Actions (co-op-translator) का उपयोग करते हुए अनुवाद प्रणाली
21- डॉक्सिफाई के माध्यम से प्रलेखन और PDF के रूप में उपलब्ध
22 
23## सेटअप कमांड
24 
25यह रिपॉजिटरी मुख्य रूप से शैक्षिक सामग्री उपभोग के लिए है। विशिष्ट परियोजनाओं के साथ काम करने के लिए:
26 
27### मुख्य रिपॉजिटरी सेटअप
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### क्विज़ ऐप सेटअप (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # विकास सर्वर शुरू करें
40npm run build      # प्रोडक्शन के लिए निर्माण करें
41npm run lint       # ESLint चलाएं
42```
43 
44### बैंक प्रोजेक्ट API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # एपीआई सर्वर शुरू करें
50npm run lint       # ESLint चलाएं
51npm run format     # Prettier के साथ फॉर्मेट करें
52```
53 
54### ब्राउज़र एक्सटेंशन परियोजनाएँ
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# ब्राउज़र-विशिष्ट एक्सटेंशन लोडिंग निर्देशों का पालन करें
60```
61 
62### स्पेस गेम परियोजनाएँ
63 
64```bash
65cd 6-space-game/solution
66npm install
67# index.html को ब्राउज़र में खोलें या लाइव सर्वर का उपयोग करें
68```
69 
70### चैट प्रोजेक्ट (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# GITHUB_TOKEN पर्यावरण चर सेट करें
76python api.py
77```
78 
79## विकास कार्यप्रवाह
80 
81### सामग्री योगदानकर्ताओं के लिए
82 
831. अपने GitHub खाते में रिपॉजिटरी को **फोर्क** करें
842. अपने फोर्क को स्थानीय रूप से **क्लोन** करें
853. अपने परिवर्तनों के लिए एक नई शाखा बनाएं
864. पाठ सामग्री या कोड उदाहरणों में परिवर्तन करें
875. संबंधित परियोजना निर्देशिकाओं में कोड परिवर्तन का परीक्षण करें
886. योगदान दिशानिर्देशों का पालन करते हुए पुल अनुरोध जमा करें
89 
90### शिक्षार्थियों के लिए
91 
921. रिपॉजिटरी को फोर्क या क्लोन करें
932. पाठ निर्देशिकाओं में क्रमबद्ध रूप से नेविगेट करें
943. प्रत्येक पाठ के README फ़ाइलें पढ़ें
954. प्री-लर्निंग क्विज़ को https://ff-quizzes.netlify.app/web/ पर पूरा करें
965. पाठ फ़ोल्डरों में कोड उदाहरणों पर काम करें
976. असाइनमेंट और चुनौतियाँ पूरी करें
987. पोस्ट-लर्निंग क्विज़ लें
99 
100### लाइव विकास
101 
102- **प्रलेखन**: रूट में `docsify serve` चलाएं (पोर्ट 3000)
103- **क्विज़ ऐप**: क्विज़-ऐप निर्देशिका में `npm run dev` चलाएं
104- **परियोजनाएँ**: HTML परियोजनाओं के लिए VS कोड लाइव सर्वर एक्सटेंशन का उपयोग करें
105- **API परियोजनाएँ**: संबंधित API निर्देशिकाओं में `npm start` चलाएं
106 
107## परीक्षण निर्देश
108 
109### क्विज़ ऐप परीक्षण
110 
111```bash
112cd quiz-app
113npm run lint       # कोड शैली की समस्याओं की जांच करें
114npm run build      # सुनिश्चित करें कि निर्माण सफल हो जाता है
115```
116 
117### बैंक API परीक्षण
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # कोड शैली मुद्दों की जांच करें
122node server.js     # यह सत्यापित करें कि सर्वर बिना त्रुटियों के शुरू होता है
123```
124 
125### सामान्य परीक्षण दृष्टिकोण
126 
127- यह एक शैक्षिक रिपॉजिटरी है जिसमें व्यापक स्वचालित परीक्षण नहीं हैं
128- मैनुअल परीक्षण पर केंद्रित:
129  - कोड उदाहरण बिना त्रुटि के चलते हैं
130  - दस्तावेज़ीकरण के लिंक सही कार्य करते हैं
131  - परियोजना बिल्ड सफलतापूर्वक पूरी होती है
132  - उदाहरण सर्वोत्तम प्रथाओं का पालन करते हैं
133 
134### सबमिशन से पहले जांच
135 
136- `package.json` वाले निर्देशिकाओं में `npm run lint` चलाएं
137- मार्कडाउन लिंक मान्य हैं यह पुष्टि करें
138- ब्राउज़र या Node.js में कोड उदाहरणों का परीक्षण करें
139- जांचें कि अनुवाद उचित संरचना बनाए रखते हैं
140 
141## कोड स्टाइल दिशानिर्देश
142 
143### जावास्क्रिप्ट
144 
145- आधुनिक ES6+ सिंटैक्स का उपयोग करें
146- परियोजनाओं में दिए गए मानक ESLint कॉन्फ़िगरेशन का पालन करें
147- शिक्षार्थियों के लिए समझने योग्य वैरिएबल और फंक्शन नामों का उपयोग करें
148- अवधारणाओं की व्याख्या करने वाले टिप्पणियाँ जोड़ें
149- जहाँ कॉन्फ़िगर हो, Prettier का उपयोग कर स्वरूपित करें
150 
151### HTML/CSS
152 
153- सेमांटिक HTML5 तत्व
154- रिस्पॉन्सिव डिज़ाइन सिद्धांत
155- स्पष्ट क्लास नामकरण कन्वेंशंस
156- CSS तकनीकों की व्याख्या करने वाली टिप्पणियाँ
157 
158### पायथन
159 
160- PEP 8 शैली दिशानिर्देश
161- साफ, शैक्षिक कोड उदाहरण
162- सीखने में मदद करने के लिए प्रकार संकेत
163 
164### मार्कडाउन दस्तावेज़ीकरण
165 
166- स्पष्ट हेडिंग पदानुक्रम
167- भाषा निर्दिष्ट कोड ब्लॉक
168- अतिरिक्त संसाधनों के लिंक
169- `images/` निर्देशिकाओं में स्क्रीनशॉट्स और चित्र
170- पहुँच के लिए छवियों के लिए alt टेक्स्ट
171 
172### फ़ाइल संगठन
173 
174- पाठ क्रम से क्रमांकित (1-getting-started-lessons, 2-js-basics, आदि)
175- प्रत्येक परियोजना में `solution/` और अक्सर `start/` या `your-work/` निर्देशिकाएँ होती हैं
176- पाठ-विशिष्ट `images/` फ़ोल्डरों में चित्र संग्रहीत
177- अनुवाद `translations/{language-code}/` संरचना में
178 
179## निर्माण और तैनाती
180 
181### क्विज़ ऐप तैनाती (Azure Static Web Apps)
182 
183क्विज़-ऐप Azure Static Web Apps तैनाती के लिए कॉन्फ़िगर किया गया है:
184 
185```bash
186cd quiz-app
187npm run build      # dist/ फ़ोल्डर बनाता है
188# मुख्य पर पुश करने पर GitHub Actions वर्कफ़्लो के माध्यम से डिप्लॉय करता है
189```
190 
191Azure Static Web Apps कॉन्फ़िगरेशन:
192- **ऐप स्थान**: `/quiz-app`
193- **आउटपुट स्थान**: `dist`
194- **वर्कफ़्लो**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### प्रलेखन PDF निर्माण
197 
198```bash
199npm install                    # docsify-to-pdf स्थापित करें
200npm run convert               # docs से PDF उत्पन्न करें
201```
202 
203### डॉक्सिफाई प्रलेखन
204 
205```bash
206npm install -g docsify-cli    # Docsify को वैश्विक रूप से स्थापित करें
207docsify serve                 # localhost:3000 पर सेवा दें
208```
209 
210### परियोजना-विशिष्ट निर्माण
211 
212प्रत्येक परियोजना निर्देशिका में अपना निर्माण प्रक्रिया हो सकती है:
213- Vue परियोजनाएँ: `npm run build` प्रोडक्शन बंडल बनाता है
214- स्थैतिक परियोजनाएँ: कोई निर्माण चरण नहीं, सीधे फ़ाइलें सेवा दें
215 
216## पुल अनुरोध दिशानिर्देश
217 
218### शीर्षक प्रारूप
219 
220स्पष्ट, वर्णनात्मक शीर्षक का उपयोग करें जो परिवर्तन क्षेत्र को दर्शाता हो:
221- `[Quiz-app] पाठ X के लिए नया क्विज़ जोड़ें`
222- `[Lesson-3] टेररियम परियोजना में वर्तनी सुधारें`
223- `[Translation] पाठ 5 के लिए स्पेनिश अनुवाद जोड़ें`
224- `[Docs] सेटअप निर्देश अपडेट करें`
225 
226### आवश्यक जांच
227 
228PR सबमिट करने से पहले:
229 
2301. **कोड गुणवत्ता**:
231   - प्रभावित परियोजना निर्देशिकाओं में `npm run lint` चलाएं
232   - सभी linting त्रुटियों और चेतावनियों को ठीक करें
233 
2342. **निर्माण सत्यापन**:
235   - जहां लागू हो, `npm run build` चलाएं
236   - सुनिश्चित करें कि कोई निर्माण त्रुटि न हो
237 
2383. **लिंक सत्यापन**:
239   - सभी मार्कडाउन लिंक का परीक्षण करें
240   - छवि संदर्भ काम करें यह जांचें
241 
2424. **सामग्री समीक्षा**:
243   - वर्तनी और व्याकरण की जांच करें
244   - सुनिश्चित करें कि कोड उदाहरण सही और शैक्षिक हैं
245   - अनुवाद मूल अर्थ को बनाए रखें
246 
247### योगदान आवश्यकताएँ
248 
249- Microsoft CLA (पहले PR पर स्वचालित जांच) से सहमत हों
250- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) का पालन करें
251- विस्तृत दिशानिर्देशों के लिए [CONTRIBUTING.md](./CONTRIBUTING.md) देखें
252- यदि लागू हो, तो PR विवरण में मुद्दा संख्या का संदर्भ दें
253 
254### समीक्षा प्रक्रिया
255 
256- PRs मेंटेनर्स और समुदाय द्वारा समीक्षा किए जाते हैं
257- शैक्षिक स्पष्टता को प्राथमिकता दी जाती है
258- कोड उदाहरणों को वर्तमान सर्वोत्तम प्रथाओं का पालन करना चाहिए
259- अनुवादों को सटीकता और सांस्कृतिक उपयुक्तता के लिए समीक्षा किया जाता है
260 
261## अनुवाद प्रणाली
262 
263### स्वचालित अनुवाद
264 
265- GitHub Actions के साथ co-op-translator वर्कफ़्लो का उपयोग करता है
266- 50+ भाषाओं में स्वचालित रूप से अनुवाद करता है
267- स्रोत फाइलें मुख्य निर्देशिकाओं में होती हैं
268- अनुवादित फाइलें `translations/{language-code}/` निर्देशिकाओं में होती हैं
269 
270### मैनुअल अनुवाद सुधार जोड़ना
271 
2721. `translations/{language-code}/` में फ़ाइल का पता लगाएं
2732. संरचना बनाए रखते हुए सुधार करें
2743. सुनिश्चित करें कि कोड उदाहरण कार्यशील बने रहें
2754. स्थानीयकृत क्विज़ सामग्री का परीक्षण करें
276 
277### अनुवाद मेटाडेटा
278 
279अनुवादित फ़ाइलों में मेटाडेटा हेडर शामिल होता है:
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## डिबगिंग और समस्या निवारण
293 
294### सामान्य समस्याएँ
295 
296**क्विज़ ऐप शुरू नहीं होता**:
297- Node.js संस्करण जांचें (v14+ अनुशंसित)
298- `node_modules` और `package-lock.json` हटाएं, फिर `npm install` चलाएं
299- पोर्ट संघर्ष जांचें (डिफ़ॉल्ट: Vite पोर्ट 5173 उपयोग करता है)
300 
301**API सर्वर शुरू नहीं होता**:
302- Node.js संस्करण न्यूनतम (node >=10) होना चाहिए
303- जांचें कि पोर्ट पहले से उपयोग में तो नहीं है
304- सुनिश्चित करें कि सभी निर्भरताएं `npm install` से स्थापित हैं
305 
306**ब्राउज़र एक्सटेंशन लोड नहीं होता**:
307- manifest.json सही फ़ॉर्मेट में है यह जांचें
308- ब्राउज़र कंसोल में त्रुटियाँ देखें
309- ब्राउज़र-विशिष्ट एक्सटेंशन इंस्टॉलेशन निर्देशों का पालन करें
310 
311**पायथन चैट प्रोजेक्ट समस्याएँ**:
312- OpenAI पैकेज स्थापित है: `pip install openai`
313- सुनिश्चित करें कि GITHUB_TOKEN पर्यावरण चर सेट है
314- GitHub मॉडल पहुँच अनुमतियाँ जांचें
315 
316**डॉक्सिफाई दस्तावेज़ सेवा नहीं करता**:
317- docsify-cli ग्लोबली स्थापित करें: `npm install -g docsify-cli`
318- रिपॉजिटरी रूट निर्देशिका से चलाएं
319- जांचें कि `docs/_sidebar.md` मौजूद है
320 
321### विकास पर्यावरण सुझाव
322 
323- HTML परियोजनाओं के लिए VS Code में लाइव सर्वर एक्सटेंशन का उपयोग करें
324- सुसंगत फॉर्मेटिंग के लिए ESLint और Prettier एक्सटेंशन इंस्टॉल करें
325- JavaScript डिबगिंग के लिए ब्राउज़र DevTools का उपयोग करें
326- Vue परियोजनाओं के लिए Vue DevTools ब्राउज़र एक्सटेंशन इंस्टॉल करें
327 
328### प्रदर्शन विचार
329 
330- अनुवादित फ़ाइलों की बड़ी संख्या (50+ भाषाएँ) के कारण पूर्ण क्लोन बड़े होते हैं
331- केवल सामग्री पर काम करने के लिए शैलो क्लोन का उपयोग करें: `git clone --depth 1`
332- अंग्रेज़ी सामग्री पर काम करते समय अनुवाद खोजों से बाहर करें
333- बिल्ड प्रक्रियाएँ पहली बार धीमी हो सकती हैं (npm install, Vite build)
334 
335## सुरक्षा विचार
336 
337### पर्यावरण चर
338 
339- API कुंजी को कभी रिपॉजिटरी में कमिट न करें
340- `.env` फ़ाइलें उपयोग करें (पहले से `.gitignore` में हैं)
341- आवश्यक पर्यावरण चर परियोजना READMEs में दस्तावेजीकृत करें
342 
343### पायथन परियोजनाएँ
344 
345- वर्चुअल एनवायरनमेंट का उपयोग करें: `python -m venv venv`
346- निर्भरताओं को अपडेट रखें
347- GitHub टोकन के पास न्यूनतम आवश्यक अनुमतियाँ होनी चाहिए
348 
349### GitHub मॉडल्स एक्सेस
350 
351- GitHub मॉडल्स के लिए व्यक्तिगत एक्सेस टोकन (PAT) आवश्यक हैं
352- टोकन को पर्यावरण चरों के रूप में सहेजें
353- टोकन या क्रेडेंशियल्स को कभी कमिट न करें
354 
355## अतिरिक्त नोट्स
356 
357### लक्षित दर्शक
358 
359- वेब विकास के पूर्ण शुरुआती
360- छात्र और स्वयं-अधिगमकर्ता
361- कक्षाओं में पाठ्यक्रम का उपयोग करने वाले शिक्षक
362- सामग्री सुलभता और धीरे-धीरे कौशल निर्माण के लिए डिज़ाइन की गई है
363 
364### शैक्षिक दर्शन
365 
366- परियोजना-आधारित सीखने का दृष्टिकोण
367- बार-बार ज्ञान जांच (क्विज़)
368- व्यावहारिक कोडिंग अभ्यास
369- वास्तविक विश्व अनुप्रयोग उदाहरण
370- फ्रेमवर्क से पहले मूल बातें पर फोकस
371 
372### रिपॉजिटरी रखरखाव
373 
374- शिक्षार्थियों और योगदानकर्ताओं की सक्रिय समुदाय
375- निर्भरताओं और सामग्री के नियमित अपडेट
376- मेंटेनर्स द्वारा मुद्दों और चर्चाओं की निगरानी
377- GitHub Actions के जरिए अनुवाद अपडेट स्वचालित
378 
379### संबंधित संसाधन
380 
381- [Microsoft Learn मॉड्यूल](https://docs.microsoft.com/learn/)
382- [स्टूडेंट हब संसाधन](https://docs.microsoft.com/learn/student-hub/)
383- शिक्षार्थियों के लिए अनुशंसित: [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
384- अतिरिक्त पाठ्यक्रम: जनरेटिव एआई, डेटा साइंस, एमएल, आईओटी पाठ्यक्रम उपलब्ध
385 
386### विशिष्ट परियोजनाओं के साथ कार्य करना
387 
388व्यक्तिगत परियोजनाओं के विस्तृत निर्देशों के लिए, README फ़ाइलें देखें:
389- `quiz-app/README.md` - Vue 3 क्विज़ एप्लिकेशन
390- `7-bank-project/README.md` - प्रमाणीकरण के साथ बैंकिंग एप्लिकेशन
391- `5-browser-extension/README.md` - ब्राउज़र एक्सटेंशन विकास
392- `6-space-game/README.md` - कैनवास-आधारित गेम डेवलपमेंट
393- `9-chat-project/README.md` - एआई चैट असिस्टेंट प्रोजेक्ट
394 
395### मोनोरिपॉ संरचना
396 
397हालांकि यह पारंपरिक मोनोरिपॉ नहीं है, इस रिपॉजिटरी में कई स्वतंत्र परियोजनाएँ हैं:
398- प्रत्येक पाठ स्वतंत्र है
399- परियोजनाएँ निर्भरताओं को साझा नहीं करती हैं
400- अन्य परियोजनाओं को प्रभावित किए बिना व्यक्तिगत परियोजनाओं पर काम करें
401- पूर्ण पाठ्यक्रम अनुभव के लिए पूरी रिपॉजिटरी क्लोन करें
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**अस्वीकृति**:  
407यह दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके अनूदित किया गया है। जबकि हम सटीकता के लिए प्रयासरत हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या गलतियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में प्राधिकृत स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए पेशेवर मानव अनुवाद की सलाह दी जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं।
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->