# AGENTS.md

## प्रकल्पाचा आढावा

हा वेब विकास मूलतत्त्वे शिकवण्यासाठी सुरुवातीच्या स्तरासाठी शैक्षणिक अभ्यासक्रम संग्रह आहे. हा अभ्यासक्रम Microsoft Cloud Advocates यांनी विकसित केलेला एक सर्वसमावेशक १२ आठवड्यांचा कोर्स आहे, ज्यामध्ये JavaScript, CSS आणि HTML या विषयांवर २४ प्रत्यक्ष शिकण्याच्या धड्यांचा समावेश आहे.

### मुख्य घटक

- **शैक्षणिक सामग्री**: प्रकल्प-आधारित मॉड्यूलमध्ये आयोजित २४ संरचित धडे
- **प्रायोगिक प्रकल्प**: Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor, आणि AI Chat Assistant
- **परस्पर संवादात्मक प्रश्नमंजुषा**: प्रत्येकी ३ प्रश्नांसह ४८ प्रश्नमंजुषा (धडा आधी/नंतरचे मूल्यमापन)
- **बहुभाषिक समर्थन**: GitHub Actions द्वारे ५०+ भाषा स्वयंचलित भाषांतर
- **तंत्रज्ञान**: 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)
- **प्रश्नमंजुषा अ‍ॅप**: `npm run dev` quiz-app डिरेक्टरीमध्ये चालवा
- **प्रकल्प**: 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` चालवा
- Markdown लिंक वैध आहेत का तपासा
- ब्राउझर किंवा Node.js मध्ये कोड उदाहरणे तपासा
- भाषांतरातील संरचना व्यवस्थित आहे का निश्चित करा

## कोड शैली मार्गदर्शक

### JavaScript

- आधुनिक ES6+ सिंटॅक्स वापरा
- प्रकल्पांत दिलेल्या मानक ESLint कॉन्फिगरेशनचे पालन करा
- शैक्षणिक स्पष्टतेसाठी अर्थपूर्ण व्हेरिएबल व फंक्शन नावे वापरा
- शिकणाऱ्यांसाठी संकल्पना समजाविणारे टिप्पणी जोडा
- जेथे प्रीटियर कॉन्फिगर आहे तिथे फॉरमॅट करा

### HTML/CSS

- सांकेतिक HTML5 घटक वापरा
- प्रतिसादात्मक डिज़ाइन तत्त्वे पाळा
- स्पष्ट वर्ग नावकरण परंपरा वापरा
- शिकणाऱ्यांसाठी CSS तंत्र आत्मसात करण्यासाठी टिप्पणी द्या

### Python

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

### Markdown दस्तऐवजीकरण

- स्पष्ट शीर्षक स्तर संरचना
- भाषा निर्दिष्ट कोड ब्लॉक्स
- अतिरिक्त संसाधनांसाठी दुवे
- `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/ फोल्डर तयार करतो
# मुख्य ब्रांचवर push झाल्यावर 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               # docs मधून PDF तयार करा
```

### Docsify दस्तऐवजीकरण

```bash
npm install -g docsify-cli    # Docsify जागतिक पातळीवर स्थापित करा
docsify serve                 # localhost:3000 वर सेवा द्या
```

### प्रकल्प-विशिष्ट बिल्ड

प्रत्येक प्रकल्प डिरेक्टरीची स्वतःची बिल्ड प्रक्रिया असू शकते:
- Vue प्रकल्प: `npm run build` उत्पादन बंडल तयार करतो
- स्थिर प्रकल्प: बिल्ड टप्पा नाही, फायली थेट सेवा करा

## पुल विनंती मार्गदर्शक

### शीर्षक स्वरूप

बदल क्षेत्र दर्शविणारी स्पष्ट, वर्णनात्मक शीर्षके वापरा:
- `[Quiz-app] Add new quiz for lesson X`
- `[Lesson-3] Fix typo in terrarium project`
- `[Translation] Add Spanish translation for lesson 5`
- `[Docs] Update setup instructions`

### आवश्यक तपासण्या

PR सादर करण्यापूर्वी:

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

2. **बिल्ड तपासणी**:
   - लागू असल्यास `npm run build` चालवा
   - बिल्ड त्रुटी नाही याची खात्री करा

3. **लिंक पुष्टीकरण**:
   - सर्व markdown लिंक तपासा
   - प्रतिमा संदर्भ कार्यरत आहेत का तपासा

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

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

- Microsoft CLA सह सहमती (पहिल्या PR वर स्वयंचलित तपासणी)
- [Microsoft Open Source कोड ऑफ कंडक्ट](https://opensource.microsoft.com/codeofconduct/) चे पालन करा
- तपशीलवार मार्गदर्शकांसाठी [CONTRIBUTING.md](./CONTRIBUTING.md) पहा
- PR वर्णनामध्ये संदर्भ असलेल्या मुद्दा क्रमांकांचा उल्लेख करा

### पुनरावलोकन प्रक्रिया

- PR प्रशासक आणि समुदायाकडून पुनरावलोकन
- शैक्षणिक स्पष्टतेला प्राधान्य
- कोड उदाहरणे विद्यमान सर्वोत्तम सरावांचे पालन करतात
- भाषांतर अचूकता आणि सांस्कृतिक सुसंगततेसाठी पुनरावलोकन केली जातात

## भाषांतर प्रणाली

### स्वयंचलित भाषांतर

- co-op-translator workflow सह GitHub Actions वापरतो
- ५०+ भाषांमध्ये स्वयंचलित भाषांतर करते
- मुख्य डिरेक्टरीजमधील स्रोत फाइल्स
- `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 मॉडेल्स प्रवेश परवानग्या तपासा

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

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

- HTML प्रकल्पांसाठी VS Code Live Server विस्तार वापरा
- सतत फॉरमॅटिंगसाठी ESLint आणि Prettier विस्तार इन्स्टॉल करा
- JavaScript डीबगिंगसाठी ब्राउझर DevTools वापरा
- Vue प्रकल्पांसाठी Vue DevTools ब्राउझर विस्तार इन्स्टॉल करा

### कार्यक्षमता विचार

- ५०+ भाषांमध्ये अनुवाद असल्यामुळे संपूर्ण क्लोन मोठा होतो
- फक्त सामग्रीवर काम करत असल्यास शालो क्लोन वापरा: `git clone --depth 1`
- इंग्रजी सामग्रीसाठी काम करताना भाषांतर शोधांमध्ये वगळा
- पहिल्या वेळी बिल्ड प्रक्रिया (npm install, Vite build) हळू असू शकते

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

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

- API की संग्रहात कधीही कमिट करू नयेत
- `.env` फायली वापरा (आधीपासून `.gitignore` मध्ये आहेत)
- प्रकल्प README मध्ये आवश्यक पर्यावरणीय चलांचे दस्तऐवजीकरण करा

### Python प्रकल्प

- वर्च्युअल वातावरण वापराः `python -m venv venv`
- अवलंबित्वे अद्ययावत ठेवा
- GitHub टोकन्सना किमान आवश्यक परवानग्या द्या

### GitHub Models प्रवेश

- GitHub मॉडेल्ससाठी वैयक्तिक प्रवेश टोकन्स (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) शिकणाऱ्यांसाठी शिफारस
- अतिरिक्त कोर्सेस: Generative AI, Data Science, 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 -->