29 KiB
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 రూపంలో అందుబాటులో ఉంటుంది
సెటప్ కమాండ్లు
ఈ గ్రంథాలయం ప్రధానంగా విద్యా విషయాల వినియోగకోసం. ప్రత్యేక ప్రాజెక్టుల పని కొరకు:
మెయిన్ రిపాజిటరీ సెటప్
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
క్విజ్ యాప్ సెటప్ (Vue 3 + Vite)
cd quiz-app
npm install
npm run dev # అభివృద్ధి సర్వర్ ప్రారంభించండి
npm run build # ఉత్పత్తి కోసం నిర్మించండి
npm run lint # ESLint నడుపండి
బ్యాంక్ ప్రాజెక్ట్ API (Node.js + Express)
cd 7-bank-project/api
npm install
npm start # API సర్వర్ ప్రారంభించండి
npm run lint # ESLint పనిచేయించండి
npm run format # Prettier తో ఆకృతి మార్చండి
బ్రౌజర్ ఎక్స్టెన్షన్ ప్రాజెక్టులు
cd 5-browser-extension/solution
npm install
# బ్రౌజర్-స్పెసిఫిక్ ఎక్స్టెన్షన్ లోడింగ్ సూచనలను అనుసరించండి
స్పేస్ గేమ్ ప్రాజెక్టులు
cd 6-space-game/solution
npm install
# బ్రౌజర్లో index.html తెరవండి లేదా లైవ్ సర్వర్ ఉపయోగించండి
చాట్ ప్రాజెక్ట్ (Python బ్యాక్ఎండ్)
cd 9-chat-project/solution/backend/python
pip install openai
# GITHUB_TOKEN'environnement משתנה సెట్ చేయండి
python api.py
అభివృద్ధి వర్క్ఫ్లో
కంటెంట్ కాంట్రిబ్యూటర్లు కోసం
- మీ GitHub ఖాతాకు రిపాజిటరీని ఫోర్క్ చేయండి
- మీ ఫోర్క్ని లోకల్గా క్లోన్ చేయండి
- మీ మార్పులకు కొత్త బ్రాంచ్ సృష్టించండి
- పాఠ అంశాలు లేదా కోడ్ ఉదాహరణలలో మార్పులు చేయండి
- సంబంధిత ప్రాజెక్ట్ డైరెక్టరీలలో ఏ కోడ్ మార్పులు టెస్ట్ చేయండి
- కాంట్రిబ్యూషన్ మార్గదర్శకాలు పాటిస్తూ పుల్ రిక్వెస్ట్లు సమర్పించండి
నేర్చుకునేవారికి
- రిపాజిటరీని ఫోర్క్ చేయండి లేదా క్లోన్ చేయండి
- పాఠం డైరెక్టరీలను క్రమంగా నావిగేట్ చేయండి
- ప్రతి పాఠం README ఫైల్స్ చదవండి
- ముందస్తు పాఠం క్విజ్లు పూర్తి చేయండి https://ff-quizzes.netlify.app/web/
- పాఠ ఫోల్డర్లలో కోడ్ ఉదాహరణల పై పని చేయండి
- అసైన్మెంట్లు, ఛాలెంజ్లు పూర్తి చేయండి
- తరువాతి పాఠం క్విజ్లు చేయండి
సజీవ అభివృద్ధి
- డాక్యుమెంటేషన్: రూట్ లో
docsify serveనడపండి (పోర్టు 3000) - క్విజ్ యాప్: quiz-app డైరెక్టరీలో
npm run devనడపండి - ప్రాజెక్టులు: HTML ప్రాజెక్టులకు VS Code Live Server ఎక్స్టెన్షన్ వాడండి
- API ప్రాజెక్టులు: సంబంధిత API డైరెక్టరీలలో
npm startనడపండి
పరీక్ష నిర్వహణ
క్విజ్ యాప్ టెస్టింగ్
cd quiz-app
npm run lint # కోడ్ శైలి సమస్యల కోసం తనిఖీ చేయండి
npm run build # బిల్డ్ విజయవంతమవుతుందో నిర్ధారించండి
బ్యాంక్ API టెస్టింగ్
cd 7-bank-project/api
npm run lint # కోడ్ శైలి సమస్యలు కోసం తనిఖీ చేయండి
node server.js # ఎటువంటి లోపాలు లేకుండా సర్వర్ ప్రారంభమవుతుందో నిర్ధారించండి
సాధారణ పరీక్ష విధానం
- ఇది విద్యా రిపాజిటరీ కనుక పూర్తి ఆటోమేటెడ్ పరీక్షలు లేవు
- మాన్యువల్ పరీక్షలు ఈ క్రింది విషయాలపై దృష్టి:
- కోడ్ ఉదాహరణలు ఎర్రర్స్ లేవని నడవడం
- డాక్యుమెంటేషన్ లో లింకులు సరిగా పని చేయడం
- ప్రాజెక్ట్ బిల్డ్స్ విజయవంతంగా పూర్తవడం
- ఉదాహరణలు ఉత్తమ పద్ధతులు అనుసరించడం
సమర్పణకు ముందు తనిఖీలు
- package.json ఉన్న డైరెక్టరీలలో
npm run lintనడపండి - మార్క్డౌన్ లింకులు చెలామణీ అవుతాయో చూడండి
- కాబ్భడిన కోడ్ ఉదాహరణలను బ్రౌజర్ లేదా Node.js లో పరీక్షించండి
- అనువాదాలు సరైన నిర్మాణం ఉంచుకున్నాయా చూడు
కోడ్ శైలి మార్గదర్శకాలు
జావాస్క్రిప్ట్
- ఆధునిక 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 కోసం కంఫిగర్ చేయబడింది:
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 ఉత్పత్తి
npm install # docsify-to-pdf ను ఇన్స్టాల్ చేయండి
npm run convert # డాక్స్ నుండి PDFను సృష్టించండి
Docsify డాక్యుమెంటేషన్
npm install -g docsify-cli # Docsify ను గ్లోబల్గా ఇన్స్టాల్ చేయండి
docsify serve # localhost:3000 పై సర్వ్ చేయండి
ప్రాజెక్ట్-వైజ్ బిల్డ్స్
ప్రతి ప్రాజెక్ట్ డైరెక్టరీకి తగినట్లుగా బిల్డ్ ప్రక్రియ ఉండవచ్చు:
- Vue ప్రాజెక్టులు:
npm run buildతో ప్రొడక్షన్ బండిల్స్ తయారు చేయబడతాయి - స్టాటిక్ ప్రాజెక్టులు: బిల్డ్ లేకుండా ఫైళ్లను నేరుగా సర్వ్ చేస్తాయి
పుల్ రిక్వెస్ట్ మార్గదర్శకాలు
శీర్షిక ఫార్మాట్
మార్పు వర్గం స్పష్టంగా సూచించే సాఫీగా వివరణాత్మక శీర్షికలు ఉపయోగించండి:
[Quiz-app] పాఠం X కోసం కొత్త క్విజ్ జోడించండి[Lesson-3] టెర్రేరియం ప్రాజెక్టులో టైపో సరి చేయండి[Translation] పాఠం 5 కి స్పానిష్ అనువాదం జోడించండి[Docs] సెటప్ సూచనలు నవీకరించండి
తప్పనిసరి తనిఖీలు
పుల్లు రిక్వెస్ట్ సమర్పించే ముందు:
-
కోడ్ నాణ్యత:
- సంబంధిత ప్రాజెక్ట్ డైరెక్టరీలలో
npm run lintనడపండి - అన్ని లింట్ తప్పిదాలు, హెచ్చరికలు సరి చేయండి
- సంబంధిత ప్రాజెక్ట్ డైరెక్టరీలలో
-
బిల్డ్ ధృవీకరణ:
- అవసరమైతే
npm run buildనడపండి - ఎటువంటి బిల్డ్ లోపాలు లేవని నిర్ధారించండి
- అవసరమైతే
-
లింక్ ధృవీకరణ:
- మార్క్డౌన్ లింకులు పనిచేస్తున్నాయో పరీక్షించండి
- చిత్రం సూచనలు సరైనవేనా చూసుకోండి
-
కంటెంట్ సమీక్ష:
- వ్యాకరణ, శైలి ప్రూఫ్ రీడింగ్ చేయండి
- కోడ్ ఉదాహరణలు సరైనవి మరియు విద్యా అనుకూలంగా ఉన్నాయి కదా చూడండి
- అనువాదాలు అసలు అర్థాన్ని సరిగ్గా ప్రతిబింబిస్తున్నాయో ధృవీకరించండి
కాంట్రిబ్యూషన్ అవసరాలు
- Microsoft CLA కు అంగీకరించండి (మొదటి పుల్ రిక్వెస్ట్ సమయంలో ఆటోమేటెడ్ చెక్)
- Microsoft Open Source కోడ్ ఆఫ్ కానడక్ట్ అనుసరించండి
- CONTRIBUTING.md లో వివరమైన మార్గదర్శకాలు చూడండి
- ఐచ్ఛికంగా PR వివరణలో సంబంధిత సమస్యల సంఖ్యలను సూచించండి
సమీక్షా ప్రక్రియ
- PR లను నిర్వహణకర్తలు మరియు కమ్యూనిటీ సమీక్షిస్తారు
- విద్యా స్పష్టతకు ప్రాధాన్యం ఇస్తారు
- కోడ్ ఉదాహరణలు నేటి ఉత్తమ పద్ధతులను అనుసరించాలి
- అనువాదాలు సక్రమత మరియు సాంస్కృతిక అనుకూలత కోసం సమీక్షిస్తారు
అనువాద వ్యవస్థ
ఆటోమేటెడ్ అనువాదం
- GitHub Actions తో co-op-translator వర్క్ఫ్లో ఉపయోగించి నిర్వ హించబడుతుంది
- ఆటోమేటిగ్గా 50+ భాషలకు అనువదిస్తుంది
- మూల ఫైళ్లు మెయిన్ డైరెక్టరీలలో ఉంటాయి
- అనువాద ఫైళ్లు
translations/{language-code}/డైరెక్టరీలలో ఉంటాయి
మాన్యువల్ అనువాద మెరుగుదలలు జోడించడం
translations/{language-code}/లో ఫైల్ కనుగొనండి- నిర్మాణం ఉంచుతూ మెరుగుదలలు చేయండి
- కోడ్ ఉదాహరణలు సరిగ్గా పనిచేస్తున్నాయా చూసుకోండి
- లోకలైజ్డ్ క్విజ్ కంటెంట్ని పరీక్షించండి
అనువాద మెటాడేటా
అనువదించబడిన ఫైళ్ళలో మెటాడేటా హెడ్డర్ ఉంటుంది:
<!--
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 ఎక్స్టెన్షన్లు ఇన్స్టాల్ చేయండి
- జావాస్క్రిప్ట్ డీబగ్గింగ్ కోసం బ్రౌజర్ 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 కొరకు వ్యక్తిగత యాక్సెస్ టోకెన్లు (PAT) అవసరం
- టోకెన్లు వాతావరణ వేరియబుల్స్ గా నిల్వ చేయండి
- టోకెన్లు లేదా సర్వ్ క్రెడెంషియల్స్ ఎప్పుడూ కమిట్ చేయవద్దు
అదనపు గమనికలు
లక్ష్య ప్రేక్షకులు
- వెబ్ డెవలప్మెంట్ లో పూర్తిగా మొదలైన వారు
- విద్యార్థులు మరియు స్వయం అభ్యాసకులు
- తరగతుల్లో ఈ పాఠ్యాంశాన్ని ఉపయోగించే ఉపాధ్యాయులు
- కంటెంట్ యాక్సెసిబిలిటీ మరియు పశ్చాత్తాపం నైపుణ్య నిర్మాణాన్ని దృష్టిలో ఉంచి రూపకం చేయబడింది
విద్యా తాత్త్వికత
- ప్రాజెక్ట్ ఆధారిత ప్రమాణం
- తరచుగా జ్ఞాన పరీక్షలు (క్విజ్లు)
- హ్యాండ్-ఆన్ కోడింగ్ వ్యాయామాలు
- నిజ జీవిత అన్వయ ఉదాహరణలు
- ఫ్రేమ్వర్క్లకు ముందు ఆధారాలను దృష్టిలో పెట్టడం
రిపాజిటరీ నిర్వహణ
- క్రియాశీలమైన కన్స్ట్రిబ్యూటర్స్ మరియు నేర్చుకునే సముదాయం
- డిపెండెన్సీలను మరియు కంటెంట్ను రెగ్యులర్ గా నవీకరించడం
- అంశాలు మరియు చర్చలు నిర్వహణకర్తలచే పరిశీలించబడతాయి
- అనువాద నవీకరణలు GitHub Actions ద్వారా ఆటోమేటెడ్ గా
సంబంధిత వనరులు
- Microsoft Learn మాడ్యూల్స్
- స్టూడెంట్ హబ్ వనరులు
- నేర్చుకునేవారికి సిఫార్సు 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 చాట్ అసిస్టెంట్ ప్రాజెక్ట్
మోనోరెపో నిర్మాణం
సంప్రదాయ మోనోరెపో అన్యాయం కాకపోయినా, ఈ రిపాజిటరీలో అనేక స్వతంత్ర ప్రాజెక్టులు ఉన్నాయి:
- ప్రతి పాఠం స్వతంత్రంగా ఉంటుంది
- ప్రాజెక్టులు డిపెండెన్సీలను పంచుకోను
- ఒక ప్రాజెక్ట్పై పని చేస్తారంటే ఇతర ప్రాజెక్టుల పనితీరు ప్రభావితమువనుకోదు
- పూర్తి కోర్సుకు పూర్తి రిపాజిటరీని క్లోన్ చేయండి
అస్పష్టం:
ఈ పత్రాన్ని AI అనువాద సేవ Co-op Translator ఉపయోగించి అనువదించబడింది. నిజసంపూర్ణత కోసం మేము ప్రయత్నిస్తున్నా, ఆటోమేటెడ్ అనువాదాలలో తప్పిదాలు లేదా అసమర్థతలు ఉండవచ్చును. మూల పత్రం దాని స్వ దేశీ భాషలోనే అధికారిక మూలం గా పరిగణించాలి. కీలక సమాచారం కోసం, నిపుణుల చేత అనువాదం సిఫార్సు చేయబడుతుంది. ఈ అనువాదం వాడకంలో ప్రయోజనాలు లేదా తప్పు అవగాహనలపై మేము బాధ్యత పెట్టుకోము.