13 KiB

Raw Permalink Blame History

AGENTS.md

Projekto apžvalga

Tai yra švietimo programa skirta mokyti pradedančiuosius interneto kūrimo pagrindų. Programa yra išsami 12 savaičių kursų sistema, sukurta Microsoft Cloud Advocates komandos, apimanti 24 praktines pamokas apie JavaScript, CSS ir HTML.

Pagrindinės sudedamosios dalys

Švietimo turinys: 24 struktūruotos pamokos, suskirstytos į projektų modulius
Praktiniai projektai: Terariumas, Rašymo žaidimas, Naršyklės plėtinys, Kosminis žaidimas, Banko programa, Kodo redaktorius ir AI pokalbių asistentas
Interaktyvūs testai: 48 testai po 3 klausimus kiekviename (prieš ir po pamokų įvertinimai)
Daugiakalbė palaikymas: Automatizuoti vertimai į 50+ kalbų naudojant GitHub Actions
Technologijos: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI projektams)

Architektūra

Švietimo saugykla su pamokomis pagrįsta struktūra
Kiekvienos pamokos aplanke yra README, kodo pavyzdžiai ir sprendimai
Atskiri projektai atskiruose kataloguose (quiz-app, įvairūs pamokų projektai)
Vertimo sistema naudojant GitHub Actions (co-op-translator)
Dokumentacija pateikiama per Docsify ir prieinama PDF formatu

Diegimo komandos

Šis saugykla yra skirta pirminiam švietimo turinio vartojimui. Dirbant su konkrečiais projektais:

Pagrindinės saugyklos paruošimas

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

Testų programėlės paruošimas (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Paleisti kūrimo serverį
npm run build      # Sukurti gamybai
npm run lint       # Vykdyti ESLint

Banko projekto API (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Paleisti API serverį
npm run lint       # Vykdyti ESLint
npm run format     # Formatuoti su Prettier

Naršyklės plėtinių projektai

cd 5-browser-extension/solution
npm install
# Vadovaukitės naršyklei būdingomis plėtinių įkėlimo instrukcijomis

Kosminio žaidimo projektai

cd 6-space-game/solution
npm install
# Atidarykite index.html naršyklėje arba naudokite Live Server

Pokalbių projektas (Python serveris)

cd 9-chat-project/solution/backend/python
pip install openai
# Nustatyti GITHUB_TOKEN aplinkos kintamąjį
python api.py

Vystymo darbo eiga

Turinį prisidedantiems

Atšakokite saugyklą į savo GitHub paskyrą
Klonuokite savo atšaką lokaliai
Sukurkite naują šaką savo pakeitimams
Atlikite turinio ar kodo pavyzdžių pakeitimus pamokose
Patikrinkite kodo pakeitimus atitinkamuose projekto kataloguose
Pateikite pull requests laikantis indėlio taisyklių

Mokiniams

Atšakokite arba klonuokite saugyklą
Eikite sekantiems pamokų katalogams paeiliui
Skaitykite kiekvienos pamokos README failus
Atlikite priešpamokinius testus https://ff-quizzes.netlify.app/web/
Dirbkite su kodo pavyzdžiais pamokų aplankuose
Atlikite užduotis ir iššūkius
Atlikite pastraipinius testus

Tiesioginis vystymas

Dokumentacija: paleiskite docsify serve pagrindiniame kataloge (portas 3000)
Testų programėlė: paleiskite npm run dev quiz-app kataloge
Projektai: naudokite VS Code Live Server plėtinį HTML projektams
API projektai: paleiskite npm start atitinkamuose API kataloguose

Testavimo instrukcijos

Testų programėlės testavimas

cd quiz-app
npm run lint       # Patikrinkite kodo stiliaus problemas
npm run build      # Patikrinkite, ar statyba sėkminga

Banko API testavimas

cd 7-bank-project/api
npm run lint       # Patikrinti kodo stiliaus problemas
node server.js     # Patvirtinti, kad serveris paleidžiamas be klaidų

Bendras testavimo metodas

Tai švietimo saugykla be išsamios automatizuotos testavimo sistemos
Rankinis testavimas orientuotas į:
- Kodo pavyzdžių vykdymą be klaidų
- Dokumentacijos nuorodų veikimą
- Projekto sėkmingą sudarymą
- Pavyzdžius atitinkančius gerąsias praktikas

Prieš pateikiant patikrinimus

Paleiskite npm run lint kataloguose su package.json
Patikrinkite markdown nuorodų galiojimą
Testuokite kodo pavyzdžius naršyklėje arba Node.js aplinkoje
Įsitikinkite, kad vertimai išlaiko tinkamą struktūrą

Kodo stiliaus gairės

JavaScript

Naudoti modernią ES6+ sintaksę
Laikytis standartinių ESLint konfigūracijų projektuose
Naudoti prasmingus kintamųjų ir funkcijų pavadinimus švietimui aiškinti
Pridėti komentarus konceptų paaiškinimui mokiniams
Formatuoti su Prettier, jei konfigūruota

HTML/CSS

Semantikos atitinkantys HTML5 elementai
Reaguojantis dizainas
Aiškios klasių pavadinimų konvencijos
Komentarai CSS technikoms paaiškinti mokiniams

Python

PEP 8 stiliaus gairės
Aiškūs, švietimui skirti kodo pavyzdžiai
Tipo užuominos, jei padeda mokymuisi

Markdown dokumentacija

Aiški antraščių hierarchija
Kodo blokai su kalbos nurodymu
Nuorodos į papildomus išteklius
Ekrano kopijos ir paveikslėliai images/ kataloguose
Alternatyvus tekstas paveikslėliams, siekiant prieinamumo

Failų organizavimas

Pamokos su numeriais paeiliui (1-getting-started-lessons, 2-js-basics ir kt.)
Kiekvienas projektas turi solution/ ir dažnai start/ arba your-work/ katalogus
Paveikslėliai saugomi pamokai priskirtuose images/ aplankuose
Vertimai saugomi translations/{language-code}/ kataloguose

Sudarymas ir diegimas

Testų programėlės diegimas (Azure Static Web Apps)

quiz-app yra sukonfigūruota Azure Static Web Apps diegimui:

cd quiz-app
npm run build      # Sukuria dist/ aplanką
# Diegia naudojant GitHub Actions darbo eigą, kai stumiama į main

Azure Static Web Apps konfiguracija:

Programėlės vieta: /quiz-app
Išvesties vieta: dist
Darbo eiga: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Dokumentacijos PDF generavimas

npm install                    # Įdiekite docsify-to-pdf
npm run convert               # Sugeneruoti PDF iš dokumentų

Docsify dokumentacija

npm install -g docsify-cli    # Įdiekite Docsify globaliai
docsify serve                 # Paleiskite serveryje localhost:3000

Projektui specifiniai sudarymai

Kiekvienas projekto katalogas gali turėti savo sudarymo procesą:

Vue projektai: npm run build sukuria gamybines pakuotes
Statiniai projektai: nėra sudarymo žingsnio, failai pateikiami tiesiogiai

Pull Request gairės

Antraštės formatas

Naudokite aiškius, aprašomuosius pavadinimus, nurodančius pakeitimo sritį:

[Quiz-app] Pridėti naują testą pamokai X
[Lesson-3] Ištaisyti klaidą terariumo projekte
[Translation] Pridėti ispanų vertimą pamokai 5
[Docs] Atnaujinti diegimo instrukcijas

Būtini patikrinimai

Prieš pateikiant PR:

Kodo kokybė:
- Paleiskite npm run lint paveiktuose projekto kataloguose
- Ištaisykite visas lint klaidas ir įspėjimus
Sudarymo patikra:
- Jei taikoma, paleiskite npm run build
- Užtikrinkite, kad nėra sudarymo klaidų
Nuorodų validacija:
- Išbandykite visas markdown nuorodas
- Patikrinkite, ar paveikslėlių nuorodos veikia
Turinio peržiūra:
- Tikrinkite rašybą ir gramatiką
- Užtikrinkite, kad kodo pavyzdžiai tinkami ir švietimo tikslais
- Patikrinkite, ar vertimai išlaiko pradinę prasmę

Indėlio reikalavimai

Sutikite su Microsoft CLA (automatinis tikrinimas pirmo PR metu)
Vadovaukitės Microsoft Open Source Code of Conduct
Peržiūrėkite CONTRIBUTING.md dėl išsamios informacijos
Nurodykite klausimų numerius PR aprašyme, jei taikoma

Apžvalgos procesas

PR apžvelgia priežiūrėtojai ir bendruomenė
Prioritetas teikiamas mokymosi aiškumui
Kodo pavyzdžiai turi laikytis dabartinių geriausių praktikų
Vertimai peržiūrimi dėl tikslumo ir kultūrinio atitikimo

Vertimo sistema

Automatizuotas vertimas

Naudoja GitHub Actions su co-op-translator darbo eiga
Automatiškai verčia į 50+ kalbų
Šaltinio failai pagrindiniuose kataloguose
Išversti failai saugomi translations/{language-code}/ kataloguose

Rankinių vertimo patobulinimų pridedimas

Suraskite failą translations/{language-code}/
Atlikite patobulinimus išlaikant struktūrą
Įsitikinkite, kad kodo pavyzdžiai veikia teisingai
Išbandykite lokalizuotą testų turinį

Vertimų metaduomenys

Išversti failai turi metaduomenų antraštę:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

Derinimas ir problemų sprendimas

Dažniausios problemos

Testų programėlė nesikrauna:

Patikrinkite Node.js versiją (rekomenduojama v14+)
Ištrinkite node_modules ir package-lock.json, paleiskite dar kartą npm install
Patikrinkite ar nėra uosto konflikto (numatytas: Vite naudoja 5173 portą)

API serveris nesikrauna:

Įsitikinkite, kad Node.js versija atitinka minimalią (node >=10)
Patikrinkite, ar uostas jau nenaudojamas
Įsitikinkite, kad visos priklausomybės įdiegtos su npm install

Naršyklės plėtinys nesikrauna:

Patikrinkite, ar manifest.json teisingai suformatuotas
Peržiūrėkite naršyklės konsolę dėl klaidų
Sekite naršyklės specifines plėtinių diegimo instrukcijas

Python pokalbių projekto problemos:

Įdiekite OpenAI paketą: pip install openai
Įsitikinkite, kad GITHUB_TOKEN aplinkos kintamasis nustatytas
Patikrinkite GitHub Models prieigos teises

Docsify neduoda dokumentų:

Įdiekite docsify-cli globaliai: npm install -g docsify-cli
Paleiskite iš saugyklos šaknies
Patikrinkite, ar egzistuoja docs/_sidebar.md

Vystymo aplinkos patarimai

Naudokite VS Code su Live Server plėtiniu HTML projektams
Įdiekite ESLint ir Prettier plėtinius nuosekliam formatavimui
Naudokite naršyklės DevTools JavaScript derinimui
Vue projektams naudokite Vue DevTools naršyklės plėtinį

Veikimo efektyvumo patarimai

Didelis išverstų failų kiekis (50+ kalbų) reiškia, kad pilni klonai dideli
Naudokite paviršinį klonavimą, jei dirbate tik su turiniu: git clone --depth 1
Dirbant su anglišku turiniu, išimkite vertimus iš paieškos
Sudarymo procesai pirmą kartą gali būti lėti (npm install, Vite build)

Saugumo aspektai

Aplinkos kintamieji

API raktai niekada neturi būti įtraukiami į saugyklą
Naudokite .env failus (jau įtraukti į .gitignore)
Reikalingi aplinkos kintamieji dokumentuojami projekto README

Python projektai

Naudokite virtualias aplinkas: python -m venv venv
Laikykite priklausomybes atnaujintas
GitHub tokenai turėtų turėti minimalias būtinas teises

GitHub Models prieiga

Reikalingi asmeniniai prieigos raktai (PAT)
Raktai turi būti saugomi kaip aplinkos kintamieji
Niekada neįtraukti jų į saugyklą ar viešinti

Papildomos pastabos

Tikslinė auditorija

Visiškai pradedantieji interneto kūrime
Studentai ir savarankiški besimokantieji
Mokytojai, naudojantys programą klasėje
Turinys sukonstruotas prieinamumui ir nuosekliam įgūdžių įgijimui

Švietimo filosofija

Mokymasis pagrįstas projektais
Dažni žinių patikrinimai (testai)
Praktiniai kodavimo užsiėmimai
Realių projektų pavyzdžiai
Dėmesys pagrindams prieš frameworks

Saugyklos priežiūra

Aktyvi mokinių ir prisidėjusių bendruomenė
Reguliarūs priklausomybių ir turinio atnaujinimai
Klausimai ir diskusijos prižiūrimi saugyklos savininkų
Vertimų atnaujinimai automatizuoti per GitHub Actions

Susiję ištekliai

Microsoft Learn moduliai
Studentų centras
GitHub Copilot rekomenduojamas besimokantiesiems
Papildomi kursai: Generatyvioji AI, Duomenų mokslas, ML, IoT programos

Darbas su konkrečiais projektais

Išsamios individualių projektų instrukcijos pateiktos README failuose:

quiz-app/README.md - Vue 3 testų programėlė
7-bank-project/README.md - Banko programa su autentifikacija
5-browser-extension/README.md - Naršyklės plėtinių kūrimas
6-space-game/README.md - Žaidimas su Canvas
9-chat-project/README.md - AI pokalbių asistento projektas

Monorepo struktūra

Nors tai nėra tradicinis monorepo, ši saugykla turi kelis nepriklausomus projektus:

Kiekviena pamoka yra savarankiška
Projektai nesidalina priklausomybėmis
Darbai su atskirais projektais neturi įtakos kitiems
Klonuokite visą saugyklą pilnam kursui gauti

Atsakomybės ribojimas: Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą Co-op Translator. Nors stengiamės užtikrinti tikslumą, atkreipkite dėmesį, kad automatizuoti vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba yra laikomas autoritetingu šaltiniu. Svarbiai informacijai rekomenduojamas profesionalus žmogiškasis vertimas. Mes neatsakome už bet kokius nesusipratimus ar klaidingas interpretacijas, kylančias naudojant šį vertimą.

13 KiB Raw Permalink Blame History