20 KiB

Raw Blame History Unescape Escape

AGENTS.md

Преглед пројекта

Ово је репозиторијум образовног курикулума за учење основа веб развоја за почетнике. Курикулум је свеобухватан 12-недељни курс који су развили Microsoft Cloud Advocates, са 24 практичне лекције које покривају JavaScript, CSS и HTML.

Кључне компоненте

Образовни садржај: 24 структурисане лекције организоване у модуле засноване на пројектима
Практични пројекти: Тераријум, игра куцања, проширење за прегледач, свемирска игра, апликација за банкарство, едитор кода и AI асистент за ћаскање
Интерактивни квизови: 48 квизова са по 3 питања (процене пре/после лекције)
Подршка за више језика: Аутоматизовани преводи на 50+ језика путем GitHub Actions
Технологије: 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        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint

API за банкарски пројекат (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier

Пројекти проширења за прегледач

cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions

Пројекти свемирске игре

cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server

Пројекат за ћаскање (Python Backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py

Радни ток развоја

За доприносиоце садржаја

Fork-ујте репозиторијум на свој GitHub налог
Клонирајте свој fork локално
Креирајте нову грану за своје измене
Направите измене у садржају лекција или примерима кода
Тестирајте измене кода у релевантним директоријумима пројеката
Поднесите pull захтеве у складу са смерницама за допринос

За ученике

Fork-ујте или клонирајте репозиторијум
Прелазите кроз директоријуме лекција редом
Читајте README датотеке за сваку лекцију
Завршите квизове пре лекције на https://ff-quizzes.netlify.app/web/
Радите на примерима кода у фасциклама лекција
Завршите задатке и изазове
Урадите квизове након лекције

Развој уживо

Документација: Покрените docsify serve у корену (порт 3000)
Апликација за квизове: Покрените npm run dev у директоријуму quiz-app
Пројекти: Користите VS Code Live Server екстензију за HTML пројекте
API пројекти: Покрените npm start у релевантним API директоријумима

Упутства за тестирање

Тестирање апликације за квизове

cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds

Тестирање API за банкарски пројекат

cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors

Општи приступ тестирању

Ово је образовни репозиторијум без свеобухватних аутоматизованих тестова
Ручно тестирање се фокусира на:
- Примери кода се извршавају без грешака
- Линкови у документацији раде исправно
- Пројекти се успешно компајлирају
- Примери следе најбоље праксе

Провере пре подношења

Покрените npm run lint у директоријумима са package.json
Проверите да ли су markdown линкови валидни
Тестирајте примере кода у прегледачу или Node.js
Проверите да ли преводи задржавају исправну структуру

Смернице за стил кода

JavaScript

Користите модеран ES6+ синтакс
Следите стандардне ESLint конфигурације које су обезбеђене у пројектима
Користите смислена имена променљивих и функција ради образовне јасноће
Додајте коментаре који објашњавају концепте за ученике
Форматирајте користећи Prettier где је конфигурисано

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:

cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main

Конфигурација Azure Static Web Apps:

Локација апликације: /quiz-app
Локација излазних датотека: dist
Workflow: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Генерисање PDF документације

npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs

Docsify документација

npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000

Изградња специфична за пројекте

Сваки директоријум пројекта може имати свој процес изградње:

Vue пројекти: npm run build креира продукцијске пакете
Статички пројекти: Нема корака изградње, директно сервирајте датотеке

Смернице за pull захтеве

Формат наслова

Користите јасне, описне наслове који указују на област измене:

[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:

Квалитет кода:
- Покрените npm run lint у релевантним директоријумима пројекта
- Исправите све грешке и упозорења lint-а
Провера изградње:
- Покрените npm run build ако је применљиво
- Уверите се да нема грешака у изградњи
Валидација линкова:
- Тестирајте све markdown линкове
- Проверите да ли референце на слике раде
Преглед садржаја:
- Проверите правопис и граматику
- Уверите се да су примери кода исправни и образовни
- Проверите да ли преводи задржавају оригинално значење

Захтеви за допринос

Сагласите се са Microsoft CLA (аутоматска провера при првом PR)
Следите Microsoft Open Source Code of Conduct
Погледајте CONTRIBUTING.md за детаљне смернице
Референцирајте бројеве проблема у опису PR ако је применљиво

Процес прегледа

PR-ове прегледају одржаваоци и заједница
Образовна јасноћа је приоритет
Примери кода треба да следе тренутне најбоље праксе
Преводи се прегледају ради тачности и културне прикладности

Систем превођења

Аутоматизовани превод

Користи GitHub Actions са co-op-translator workflow-ом
Аутоматски преводи на 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 постоји

Савети за развојно окружење

Користите VS Code са Live Server екстензијом за HTML пројекте
Инсталирајте ESLint и Prettier екстензије за конзистентно форматирање
Користите DevTools прегледача за дебаговање JavaScript-а
За Vue пројекте, инсталирајте Vue DevTools екстензију за прегледач

Разматрања перформанси

Велики број преведених датотека (50+ језика) значи да су пуни клони велики
Користите плитко клонирање ако радите само на садржају: git clone --depth 1
Искључите преводе из претраге када радите на садржају на енглеском
Процеси изградње могу бити спори при првом покретању (npm install, Vite build)

Разматрања безбедности

Променљиве окружења

API кључеви никада не треба да буду послати у репозиторијум
Користите .env датотеке (већ у .gitignore)
Документирајте потребне променљиве окружења у README датотекама пројекта

Python пројекти

Користите виртуелна окружења: python -m venv venv
Одржавајте зависности ажурним
GitHub токени треба да имају минималне потребне дозволе

Приступ GitHub Models

Personal Access Tokens (PAT) су потребни за GitHub Models
Токени треба да буду чувани као променљиве окружења
Никада не шаљите токене или креденцијале

Додатне напомене

Циљна публика

Потпуни почетници у веб развоју
Студенти и самоуки ученици
Наставници који користе курикулум у учионицама
Садржај је дизајниран за приступачност и постепено стицање вештина

Образовна филозофија

Приступ учењу заснован на пројектима
Честа провера знања (квизови)
Практичне вежбе кодирања
Примери примене у стварном свету
Фокус на основама пре коришћења оквира

Одржавање репозиторијума

Активна заједница ученика и доприносиоца
Редовна ажурирања зависности и садржаја
Проблеми и дискусије прати тим одржаваоца
Ажурирања превода аутоматизована преко 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 - Развој игара заснованих на Canvas-у
9-chat-project/README.md - Пројекат AI асистента за ћаскање

Структура монорепозиторијума

Иако није традиционални монорепозиторијум, овај репозиторијум садржи више независних пројеката:

Свака лекција је самостална
Пројекти не деле зависности
Радите на појединачним пројектима без утицаја на друге
Клонирајте цео репозиторијум за потпуно искуство курикулума

Одрицање од одговорности:
Овај документ је преведен коришћењем услуге за превођење помоћу вештачке интелигенције Co-op Translator. Иако се трудимо да обезбедимо тачност, молимо вас да имате у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати меродавним извором. За критичне информације препоручује се професионални превод од стране људи. Не преузимамо одговорност за било каква погрешна тумачења или неспоразуме који могу настати услед коришћења овог превода.

20 KiB Raw Blame History Unescape Escape