# AGENTS.md

## प्रोजेक्ट अवलोकन

यह शुरुआती लोगों को वेब विकास की बुनियाद सिखाने के लिए एक शैक्षिक पाठ्यक्रम रिपॉजिटरी है। यह पाठ्यक्रम Microsoft Cloud Advocates द्वारा विकसित एक व्यापक 12-सप्ताह का कोर्स है, जिसमें JavaScript, CSS और HTML को कवर करने वाले 24 व्यावहारिक पाठ शामिल हैं।

### मुख्य घटक

- **शैक्षिक सामग्री**: 24 संरचित पाठ, जो प्रोजेक्ट-आधारित मॉड्यूल में व्यवस्थित हैं
- **व्यावहारिक प्रोजेक्ट्स**: टेरारियम, टाइपिंग गेम, ब्राउज़र एक्सटेंशन, स्पेस गेम, बैंकिंग ऐप, कोड एडिटर, और AI चैट असिस्टेंट
- **इंटरैक्टिव क्विज़**: 48 क्विज़, प्रत्येक में 3 प्रश्न (प्री/पोस्ट-लेसन आकलन)
- **मल्टी-भाषा समर्थन**: GitHub Actions के माध्यम से 50+ भाषाओं में स्वचालित अनुवाद
- **प्रौद्योगिकियां**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI प्रोजेक्ट्स के लिए)

### वास्तुकला

- पाठ आधारित संरचना के साथ शैक्षिक रिपॉजिटरी
- प्रत्येक पाठ फ़ोल्डर में README, कोड उदाहरण, और समाधान शामिल हैं
- अलग-अलग निर्देशिकाओं में स्वतंत्र प्रोजेक्ट्स (quiz-app, विभिन्न पाठ प्रोजेक्ट्स)
- GitHub Actions (co-op-translator) द्वारा अनुवाद प्रणाली
- Docsify द्वारा सेवा प्रदत्त दस्तावेज़ और PDF के रूप में उपलब्ध

## सेटअप कमांड्स

यह रिपॉजिटरी मुख्य रूप से शैक्षिक सामग्री उपभोग के लिए है। विशिष्ट प्रोजेक्ट्स के साथ काम करने के लिए:

### मुख्य रिपॉजिटरी सेटअप

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

### क्विज़ ऐप सेटअप (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # विकास सर्वर प्रारंभ करें
npm run build      # उत्पादन के लिए निर्माण करें
npm run lint       # ESLint चलाएँ
```

### बैंक प्रोजेक्ट API (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # API सर्वर शुरू करें
npm run lint       # ESLint चलाएं
npm run format     # Prettier से फ़ॉर्मेट करें
```

### ब्राउज़र एक्सटेंशन प्रोजेक्ट्स

```bash
cd 5-browser-extension/solution
npm install
# ब्राउज़र-विशिष्ट एक्सटेंशन लोडिंग निर्देशों का पालन करें
```

### स्पेस गेम प्रोजेक्ट्स

```bash
cd 6-space-game/solution
npm install
# ब्राउज़र में index.html खोलें या Live Server का उपयोग करें
```

### चैट प्रोजेक्ट (Python Backend)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# GITHUB_TOKEN पर्यावरण चर सेट करें
python api.py
```

## विकास कार्यप्रवाह

### सामग्री योगदानकर्ताओं के लिए

1. **अपने GitHub खाते में रिपॉजिटरी को फोर्क करें**
2. **अपने फोर्क को स्थानीय रूप से क्लोन करें**
3. **अपनी परिवर्तनों के लिए एक नया ब्रांच बनाएं**
4. पाठ सामग्री या कोड उदाहरणों में परिवर्तन करें
5. संबंधित प्रोजेक्ट निर्देशिकाओं में कोड परिवर्तन परीक्षण करें
6. योगदान दिशानिर्देशों का पालन करते हुए पुल अनुरोध सबमिट करें

### शिक्षार्थियों के लिए

1. रिपॉजिटरी को फोर्क या क्लोन करें
2. अनुक्रमिक रूप से पाठ निर्देशिकाओं में जाएं
3. प्रत्येक पाठ के README फ़ाइलें पढ़ें
4. https://ff-quizzes.netlify.app/web/ पर प्री-लेसन क्विज़ पूरी करें
5. पाठ फ़ोल्डर्स में कोड उदाहरणों पर काम करें
6. असाइनमेंट और चुनौतियां पूरी करें
7. पोस्ट-लेसन क्विज़ लें

### लाइव विकास

- **दस्तावेज़ीकरण**: रूट में `docsify serve` चलाएं (पोर्ट 3000)
- **क्विज़ ऐप**: `quiz-app` निर्देशिका में `npm run dev` चलाएं
- **प्रोजेक्ट्स**: HTML प्रोजेक्ट्स के लिए VS Code Live Server विस्तार का उपयोग करें
- **API प्रोजेक्ट्स**: संबंधित API निर्देशिकाओं में `npm start` चलाएं

## परीक्षण निर्देश

### क्विज़ ऐप परीक्षण

```bash
cd quiz-app
npm run lint       # कोड स्टाइल की समस्याओं के लिए जांच करें
npm run build      # सत्यापित करें कि बिल्ड सफल होता है
```

### बैंक API परीक्षण

```bash
cd 7-bank-project/api
npm run lint       # कोड शैली की समस्याओं की जांच करें
node server.js     # सुनिश्चित करें कि सर्वर त्रुटियों के बिना शुरू होता है
```

### सामान्य परीक्षण दृष्टिकोण

- यह एक शैक्षिक रिपॉजिटरी है जिसमें व्यापक स्वचालित परीक्षण नहीं हैं
- मैनुअल परीक्षण इस बात पर केंद्रित है:
  - कोड उदाहरण बिना त्रुटि के चलें
  - दस्तावेज़ में लिंक सही काम करें
  - प्रोजेक्ट सफलतापूर्वक बिल्ड हों
  - उदाहरण सर्वोत्तम प्रथाओं का पालन करें

### प्री-समर्पण जाँच

- package.json वाले निर्देशिकाओं में `npm run lint` चलाएं
- मार्कडाउन लिंक मान्य हैं या नहीं जांचें
- ब्राउज़र या Node.js में कोड उदाहरणों का परीक्षण करें
- सुनिश्चित करें कि अनुवाद संरचना को सही बनाए रखें

## कोड स्टाइल दिशानिर्देश

### JavaScript

- आधुनिक ES6+ सिंटैक्स का उपयोग करें
- प्रोजेक्ट्स में दिए गए मानक ESLint कॉन्फ़िगरेशन का पालन करें
- शैक्षिक स्पष्टता के लिए अर्थपूर्ण वेरिएबल और फ़ंक्शन नाम उपयोग करें
- शिक्षार्थियों के लिए अवधारणाओं को समझाने वाले टिप्पणियाँ जोड़ें
- जहां कॉन्फ़िगर किया गया है वहां Prettier से स्वरूपित करें

### HTML/CSS

- सेमांटिक HTML5 तत्वों का उपयोग करें
- उत्तरदायी डिज़ाइन सिद्धांत अपनाएं
- स्पष्ट क्लास नामकरण कन्वेंशन
- शिक्षार्थियों के लिए CSS तकनीकों को समझाने वाले टिप्पणियां

### Python

- PEP 8 स्टाइल दिशानिर्देशों का पालन करें
- स्पष्ट, शैक्षिक कोड उदाहरण
- सीखने के लिए जहां उपयोगी हो टाइप संकेत उपयोग करें

### मार्कडाउन दस्तावेज़ीकरण

- स्पष्ट शीर्षक अनुक्रम
- भाषा निर्दिष्ट किए गए कोड ब्लॉक
- अतिरिक्त संसाधनों के लिंक
- `images/` निर्देशिकाओं में स्क्रीनशॉट और चित्र
- पहुँचनीयता के लिए इमेज के लिए Alt टेक्स्ट

### फ़ाइल संगठन

- पाठ क्रमांकित (1-getting-started-lessons, 2-js-basics, आदि)
- प्रत्येक प्रोजेक्ट में `solution/` और अक्सर `start/` या `your-work/` निर्देशिकाएं
- पाठ-विशिष्ट `images/` फ़ोल्डर्स में इमेज संग्रहित
- अनुवाद `translations/{language-code}/` संरचना में

## बिल्ड और डिप्लॉयमेंट

### क्विज़ ऐप डिप्लॉयमेंट (Azure Static Web Apps)

क्विज़ ऐप Azure Static Web Apps डिप्लॉयमेंट के लिए कॉन्फ़िगर है:

```bash
cd quiz-app
npm run build      # dist/ फ़ोल्डर बनाता है
# मुख्य शाखा पर पुश करने पर GitHub Actions वर्कफ़्लो के माध्यम से तैनात करता है
```

Azure Static Web Apps कॉन्फ़िगरेशन:
- **ऐप स्थान**: `/quiz-app`
- **आउटपुट स्थान**: `dist`
- **कार्यप्रवाह**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### दस्तावेज़ीकरण PDF निर्माण

```bash
npm install                    # docsify-to-pdf स्थापित करें
npm run convert               # डॉक से पीडीएफ बनाएँ
```

### Docsify दस्तावेज़ीकरण

```bash
npm install -g docsify-cli    # Docsify को ग्लोबली इंस्टॉल करें
docsify serve                 # localhost:3000 पर सर्व करें
```

### प्रोजेक्ट-विशिष्ट बिल्ड्स

प्रत्येक प्रोजेक्ट निर्देशिका का अपना बिल्ड प्रक्रिया हो सकता है:
- Vue प्रोजेक्ट्स में: `npm run build` उत्पादन बंडल बनाता है
- स्थैतिक प्रोजेक्ट्स में: कोई बिल्ड स्टेप नहीं, सीधे फाइल सेवा करें

## पुल अनुरोध दिशानिर्देश

### शीर्षक प्रारूप

स्पष्ट, वर्णनात्मक शीर्षक का उपयोग करें जो परिवर्तन क्षेत्र को दर्शाए:
- `[Quiz-app] पाठ X के लिए नया क्विज़ जोड़ें`
- `[Lesson-3] टेरारियम प्रोजेक्ट में टाइपो ठीक करें`
- `[Translation] पाठ 5 के लिए स्पेनिश अनुवाद जोड़ें`
- `[Docs] सेटअप निर्देश अपडेट करें`

### आवश्यक जाँच

PR सबमिट करने से पहले:

1. **कोड गुणवत्ता**:
   - प्रभावित प्रोजेक्ट निर्देशिकाओं में `npm run lint` चलाएं
   - सभी लिंटिंग त्रुटियों और चेतावनियों को ठीक करें

2. **बिल्ड सत्यापन**:
   - लागू होने पर `npm run build` चलाएं
   - किसी बिल्ड त्रुटि को सुनिश्चित न करें

3. **लिंक सत्यापन**:
   - सभी मार्कडाउन लिंक जांचें
   - इमेज रेफरेंस काम करते हैं सुनिश्चित करें

4. **सामग्री समीक्षा**:
   - वर्तनी और व्याकरण जांचें
   - कोड उदाहरण सही और शैक्षिक हों
   - अनुवाद मूल अर्थ बनाए रखें

### योगदान आवश्यकताएं

- Microsoft CLA (पहले PR पर स्वचालित जांच) पर सहमति दें
- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) का पालन करें
- विस्तृत दिशानिर्देशों के लिए [CONTRIBUTING.md](./CONTRIBUTING.md) देखें
- यदि लागू हो तो PR विवरण में इश्यू नंबर संदर्भित करें

### समीक्षा प्रक्रिया

- PR का देखभालकर्ताओं और समुदाय द्वारा मूल्यांकन किया जाता है
- शैक्षिक स्पष्टता प्राथमिकता है
- कोड उदाहरण वर्तमान सर्वोत्तम प्रथाओं का पालन करें
- अनुवाद सटीकता और सांस्कृतिक उपयुक्तता के लिए समीक्षा होती है

## अनुवाद प्रणाली

### स्वचालित अनुवाद

- GitHub Actions के साथ co-op-translator कार्यप्रवाह का उपयोग करता है
- 50+ भाषाओं में स्वचालित अनुवाद करता है
- मुख्य निर्देशिकाओं में स्रोत फाइलें
- अनुवादित फाइलें `translations/{language-code}/` निर्देशिकाओं में

### मैनुअल अनुवाद सुधार जोड़ना

1. `translations/{language-code}/` में फाइल खोजें
2. संरचना बनाए रखते हुए सुधार करें
3. सुनिश्चित करें कि कोड उदाहरण कार्यशील बने रहें
4. स्थानीयकृत क्विज़ सामग्री का परीक्षण करें

### अनुवाद मेटाडेटा

अनुवादित फाइलों में मेटाडेटा हेडर होता है:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

## डिबगिंग और समस्या निवारण

### सामान्य समस्याएं

**क्विज़ ऐप शुरू नहीं होता**:
- Node.js का संस्करण चेक करें (v14+ अनुशंसित)
- `node_modules` और `package-lock.json` हटाएं, फिर `npm install` चलाएं
- पोर्ट संघर्ष देखें (डिफॉल्ट: Vite पोर्ट 5173 उपयोग करता है)

**API सर्वर शुरू नहीं होता**:
- Node.js संस्करण न्यूनतम आवश्यकतानुसार हो (node >=10)
- पोर्ट पहले से उपयोग में है या नहीं जांचें
- सभी निर्भरताएं `npm install` से इंस्टॉल हों

**ब्राउज़र एक्सटेंशन लोड नहीं होता**:
- manifest.json ठीक से फॉर्मेट किया गया है जांचें
- ब्राउज़र कंसोल में त्रुटियां देखें
- ब्राउज़र-विशिष्ट एक्सटेंशन इंस्टॉलेशन निर्देशों का पालन करें

**Python चैट प्रोजेक्ट समस्याएं**:
- OpenAI पैकेज इंस्टॉल है: `pip install openai`
- GITHUB_TOKEN पर्यावरण चर सेट है
- GitHub Models एक्सेस अनुमति जांचें

**Docsify दस्तावेज़ नहीं सेवा कर रहा**:
- docsify-cli ग्लोबली इंस्टॉल करें: `npm install -g docsify-cli`
- रिपॉजिटरी रूट डायरेक्टरी से चलाएं
- `docs/_sidebar.md` मौजूद है जांचें

### विकास पर्यावरण टिप्स

- HTML प्रोजेक्ट्स के लिए VS Code में Live Server एक्सटेंशन का उपयोग करें
- सुसंगत स्वरूपण के लिए ESLint और Prettier एक्सटेंशन इंस्टॉल करें
- JavaScript डिबगिंग के लिए ब्राउज़र DevTools का उपयोग करें
- Vue प्रोजेक्ट्स के लिए Vue DevTools ब्राउज़र एक्सटेंशन इंस्टॉल करें

### प्रदर्शन विचार

- अनुवादित बड़ी संख्या की फाइलें (50+ भाषाएं) पूरी क्लोन बड़ी होती है
- केवल कंटेंट पर काम करने के लिए शैलो क्लोन का उपयोग करें: `git clone --depth 1`
- अंग्रेज़ी सामग्री पर काम करते समय अनुवाद खोज से बाहर करें
- बिल्ड प्रक्रियाएं पहली बार धीमी हो सकती हैं (npm install, Vite बिल्ड)

## सुरक्षा विचार

### पर्यावरण चर

- API कुंजी कभी रिपॉजिटरी में कमिट न करें
- `.env` फाइलों का उपयोग करें (पहले से `.gitignore` में है)
- परियोजना READMEs में आवश्यक पर्यावरण चर दस्तावेज़ित करें

### Python प्रोजेक्ट्स

- वर्चुअल एनवायरनमेंट्स का उपयोग करें: `python -m venv venv`
- निर्भरताएं अपडेट रखें
- GitHub टोकन न्यूनतम आवश्यक अनुमतियां रखें

### GitHub Models एक्सेस

- GitHub Models के लिए Personal Access Tokens (PAT) आवश्यक
- टोकन को पर्यावरण चर के रूप में स्टोर करें
- टोकन या प्रमाणपत्र कभी कमिट न करें

## अतिरिक्त नोट्स

### लक्षित दर्शक

- वेब विकास के पूर्ण शुरुआती
- छात्र और स्वयं-अध्ययनकर्ता
- कक्षाओं में पाठ्यक्रम का उपयोग करने वाले शिक्षक
- सामग्री पहुँचनीयता और क्रमिक कौशल निर्माण के लिए डिज़ाइन की गई है

### शैक्षिक दर्शन

- प्रोजेक्ट-आधारित सीखने का दृष्टिकोण
- बार-बार ज्ञान जाँच (क्विज़)
- व्यावहारिक कोडिंग अभ्यास
- वास्तविक दुनिया के अनुप्रयोग उदाहरण
- फ्रेमवर्क से पहले मूल सिद्धांतों पर ध्यान

### रिपॉजिटरी रखरखाव

- सक्रिय शिक्षार्थी और योगदानकर्ता समुदाय
- निर्भरताओं और सामग्री के नियमित अपडेट
- देखभालकर्ताओं द्वारा इश्यू और चर्चा की निगरानी
- अनुवाद अपडेट GitHub Actions द्वारा स्वचालित

### संबंधित संसाधन

- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) शिक्षार्थियों के लिए अनुशंसित
- अतिरिक्त पाठ्यक्रम: जनरेटिव AI, डेटा साइंस, ML, IoT पाठ्यक्रम उपलब्ध

### विशिष्ट प्रोजेक्ट्स के साथ काम करना

व्यक्तिगत प्रोजेक्ट्स के विस्तृत निर्देश के लिए, निम्न README फाइलों को देखें:
- `quiz-app/README.md` - Vue 3 क्विज़ एप्लिकेशन
- `7-bank-project/README.md` - प्रमाणीकरण के साथ बैंकिंग ऐप्लिकेशन
- `5-browser-extension/README.md` - ब्राउज़र एक्सटेंशन विकास
- `6-space-game/README.md` - कैनवास-आधारित गेम विकास
- `9-chat-project/README.md` - AI चैट असिस्टेंट प्रोजेक्ट

### मोनोरिपो संरचना

हालांकि यह पारंपरिक मोनोरिपो नहीं है, इस रिपॉजिटरी में कई स्वतंत्र प्रोजेक्ट्स हैं:
- प्रत्येक पाठ स्वतंत्र है
- प्रोजेक्ट्स निर्भरताएं साझा नहीं करते
- एक प्रोजेक्ट पर काम करें बिना दूसरों को प्रभावित किए
- पूरा पाठ्यक्रम अनुभव के लिए पूरी रिपॉजिटरी क्लोन करें

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**अस्वीकरण**:  
इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयासरत हैं, कृपया ध्यान दें कि स्वचालित अनुवाद में त्रुटियाँ या असत्यताएँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सलाह दी जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं।
<!-- CO-OP TRANSLATOR DISCLAIMER END -->