# AGENTS.md ## ప్రాజెక్ట్ అవలోకనం ఇది ప్రారంభికులకు వెబ్ డెవలప్‌మెంట్ మౌలికాంశాలను బోధించడానికి విద్యావేత్తా పాఠ్యక్రమం రిపోజిటరీ. ఈ పాఠ్యక్రమం మైక్రోసాఫ్ట్ క్లౌడ్ అడ్వొకేట్స్ అభివృద్ధి చేసిన సమగ్ర 12 వారాల కోర్సు, 24 ప్రాక్టికల్ పాఠాలు JavaScript, CSS, మరియు HTML ప్రస్తావిస్తూ ఉంటుంది. ### ముఖ్య భాగాలు - **విద్యా కంటెంట్**: ప్రాజెక్ట్ ఆధారిత మాడ్యూల్స్‌లో 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 ``` ### Quiz App సెట్‌అప్ (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 బ్యాక్ ఎండ్) ```bash cd 9-chat-project/solution/backend/python pip install openai # GITHUB_TOKEN పర్యావరణ చ变数ను సెట్ చేయండి python api.py ``` ## అభివృద్ధి కార్యకలాపం ### కంటెంట్ కాంట్రిబ్యూటర్ల కోసం 1. రిపోజిటరీని మీ GitHub అకౌంట్‌కు **fork** చేయండి 2. మీ forkను లోకలీ **clone** చేసుకోండి 3. మీ మార్పుల కోసం కొత్త బ్రాంచ్ **create** చేయండి 4. పాఠ కంటెంట్ లేదా కోడ్ ఉదాహరణలలో మార్పులు చేయండి 5. సంబంధిత ప్రాజెక్టు డైరెక్టరీలలో కోడ్ మార్పులను పరీక్షించండి 6. కాంట్రిబ్యూషన్ మార్గదర్శకాలు అనుసరించి pull requests సమర్పించండి ### అభ్యాసకుల కోసం 1. రిపోజిటరీని fork లేదా clone చేయండి 2. పాఠం డైరెక్టరీల ద్వారా క్రమంగా వెళ్లండి 3. ప్రతి పాఠం README ఫైళ్లు చదవండి 4. ముందస్తు క్విజ్‌లను https://ff-quizzes.netlify.app/web/ వద్ద పూర్తి చేయండి 5. పాఠ ఫోల్డర్లలో కోడ్ ఉదాహరణలపై పని చేయండి 6. అసైన్మెంట్లు మరియు ఛాలెంజ్‌లను పూర్తి చేయండి 7. తరువాత క్విజ్‌లను పూర్తి చేయండి ### లైవ్ అభివృద్ధి - **డాక్యుమెంటేషన్**: రూట్‌లో `docsify serve` నడపండి (పోర్ట్ 3000) - **Quiz App**: quiz-app డైరెక్టరీలో `npm run dev` నడపండి - **ప్రాజెక్టులు**: HTML ప్రాజెక్టుల కోసం VS Code Live Server ఎక్స్‌టెన్షన్ ఉపయోగించండి - **API ప్రాజెక్టులు**: సంబంధిత API డైరెక్టరీలో `npm start` నడపండి ## టెస్టింగ్ సూచనలు ### Quiz App టెస్టింగ్ ```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 నియమాలను అనుసరించండి - విద్యార్థులకు అర్థం కావాల్సిన విధంగా వరియబుల్ మరియు ఫంక్షన్ పేర్లను ఉంచండి - నేర్చుకునేవారికి స్పష్టమైన వ్యాఖ్యలు జోడించండి - Prettier తో ఫార్మాటింగ్ చేయండి (అక్కడ అమర్చి ఉంటే) ### HTML/CSS - Semantic HTML5 ఎలిమెంట్లు - స్పందనాత్మక డిజైన్ సూత్రాలు - పరిశుభ్రమైన క్లాస్ నామకరణ నియమాలు - CSS సాంకేతికాలపై విధేయుల కోసం వ్యాఖ్య‌లు ### Python - PEP 8 శైలీ మార్గదర్శకాలు - స్పష్టమైన, విద్యా కోడ్ ఉదాహరణలు - నేర్చుకోవడంలో సహాయమయ్యే తీప్ సూచనలు ### Markdown డాక్యుమెంటేషన్ - స్పష్టమైన శీర్షిక యథార్థ శ్రేణి - భాషా స్పెసిఫికేషన్‌తో కోడ్ బ్లాక్‌లు - అదనపు వనరులకు లింకులు - `images/` ఫోల్డర్‌లలో స్క్రీన్శాట్లు మరియు చిత్రాలు - పిక్చర్లకు alt టెక్స్ accessibility కోసం ### ఫైల్ అవసరం - పాఠాలు ధారామూలంగా numbering(1-getting-started-lessons, 2-js-basics, ఇతరాలు) - ప్రతి ప్రాజెక్టుకు `solution/` మరియు చాలాసార్లు `start/` లేదా `your-work/` ఫోల్డర్లు ఉంటాయి - చిత్రాలు పాఠం-ప్రత్యేక `images/` ఫోల్డర్‌లలో నిల్వ ఉంటాయి - అనువాదాలు `translations/{language-code}/` నిర్మాణంలో ఉంటాయి ## బిల్డ్ మరియు డిప్లాయ్‌మెంట్ ### Quiz App డిప్లాయ్‌మెంట్ (Azure Static Web Apps) quiz-app 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 # docs నుండి PDF సృష్టించండి ``` ### 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` నడపండి - అన్ని lint లోపాలు మరియు హెచ్చరికలను సరి చేయండి 2. **బిల్డ్ ధృవీకరణ**: - అవసరమైతే `npm run build` నడపండి - ఎలాంటి బిల్డ్ లోపాలు లేనట్టు చూడండి 3. **లింక్ ధృవీకరణ**: - అన్ని Markdown లింకులను పరీక్షించండి - చిత్ర సూచనలు పనిచేస్తాయా చూడండి 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 ``` ## డీబగ్గింగ్ మరియు సమస్య పరిష్కారం ### సామాన్య సమస్యలు **Quiz app ప్రారంభం అవ్వడం లేదు**: - 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 build) ## భద్రతా పరిగణనలు ### ఎన్విరాన్‌మెంట్ వేరియబుల్స్ - API కీలు ఎప్పుడూ రిపోజిటరీకి కమిట్ చేయవద్దు - `.env` ఫైల్స్ ఉపయోగించండి (`.gitignore` లో ఉన్నాయి) - అవసరమైన ఎన్విరాన్‌మెంట్ వేరియబుల్స్ ప్రాజెక్ట్ READMEల్లో డాక్యుమెంట్ చేయండి ### Python ప్రాజెక్టులు - వర్చువల్ ఎన్విరాన్‌మెంట్లు ఉపయోగించండి: `python -m venv venv` - డిపెండెన్సీలు అప్డేట్ లో ఉంచండి - GitHub టోకెన్స్ కు కనీస అవసర అనుమతులు ఉండాలి ### GitHub Models యాక్సెస్ - GitHub Modelsకి Personal Access Tokens (PAT) అవసరం - టోకెన్స్ ఎన్విరాన్‌మెంట్ వేరియబుల్స్ లో నిల్వ చేయాలి - ఎప్పుడూ టోకెన్స్ లేదా క్రెడెన్షియల్స్ కమిట్ చేయవద్దు ## అదనపు గమనికలు ### లక్ష్య ప్రేక్షకులు - వెబ్ డెవలప్‌మెంట్ లో పూర్తిగా కొత్తవారు - విద్యార్థులు మరియు స్వయం-అభ్యాసకులు - తరగతి గదుల్లో పాఠ్యక్రమం ఉపయోగించే ఉపాధ్యాయులు - కంటెంట్ సాధారణ ప్రజల కోసం సులభతరం మరియు స్థిరంగా తయారు చేయబడింది ### విద్యా తత్వం - ప్రాజెక్ట్-ఆధారిత నేర్పింపు విధానం - తరచుగా జ్ఞానం పరీక్షలు (క్విజ్‌లు) - ప్రాక్టికల్ కోడింగ్ వ్యాయామాలు - వాస్తవ ప్రపంచ అప్లికేషన్ ఉదాహరణలు - ఫ్రేమ్‌వర్క్‌ల ముందు మౌలికాంశాలపై ఫోకస్ ### రిపోజిటరీ నిర్వహణ - విద్యార్థులు మరియు కాంట్రిబ్యూటర్ల సജീവ సమాజం - డిపెండెన్సీలు మరియు కంటెంట్ రెగ్యులర్ అప్‌డేట్లు - ఇష్యూస్ మరియు చర్చలు నిర్వహకులు పరిశీలనలో ఉంచుతారు - అనువాదం అప్‌డేట్లు GitHub Actionsతో ఆటోమేటెడ్ ### సంబంధిత వనరులు - [Microsoft Learn మాడ్యూల్‌లు](https://docs.microsoft.com/learn/) - [Student Hub వనరులు](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 quiz అప్లికేషన్ - `7-bank-project/README.md` - బ్యాంకింగ్ యాప్ ఆథెంటికేషన్ తో - `5-browser-extension/README.md` - బ్రౌజర్ విస్తరణ అభివృద్ధి - `6-space-game/README.md` - క్యాన్వాస్ ఆధారిత గేమ్ అభివృద్ధి - `9-chat-project/README.md` - AI చాట్ అసిస్టెంట్ ప్రాజెక్ట్ ### మోనోరిపో నిర్మాణం సాంప్రదాయ మోనోరిపో కాకపోయినా, ఈ రిపోజిటరీలో బహుళ స్వతంత్ర ప్రాజెక్టులు ఉన్నాయి: - ప్రతి పాఠం స్వతంత్రం - ప్రాజెక్టులు డిపెండెన్సీలను పంచుకోరు - ఇతర ప్రాజెక్టులను ప్రభావితం చేయకుండా వేరు వేరు ప్రాజెక్టులపై పని చేయండి - పూర్తి పాఠ్యక్రమం అనుభవం కోసం మొత్తం రిపోజిటరీని clone చేయండి --- **అస्वीకారం**: ఈ దస్తావేజును AI అనువాద సేవ అయిన [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నిస్తున్నప్పటికీ, ఆటోమేటిక్ అనువాదంలో పొరపాట్లు లేదా అసమర్థతలు ఉండవచ్చు. మూల దస్తావేజు దాని స్వదేశీ భాషలో అధికారిక వనరుగా ఉండాలి. ముఖ్య సమాచారం కోసం, వృత్తిపరమైన మానవ అనువాదాన్ని సూచించబడింది. ఈ అనువాదాన్ని ఉపయోగించడంవల్ల కలిగే ఏవైనా అవగాహనలో పొరపాట్ల లేదా అపార్థాల కోసం మేము బాధ్యులు కాదు.