20 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

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

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

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

Образовни садржај: 24 структурирана часа организована у модуле засноване на пројектима
Практични пројекти: Терраријум, Typing Game, Browser Extension, Space Game, Banking App, Code Editor и AI Chat Assistant
Интерактивни квизови: 48 квизова са по 3 питања (процена пре и после часа)
Подршка за више језика: Аутоматски преводи за 50+ језика преко GitHub Actions
Технологије: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (за AI пројекте)

Архитектура

Образовни репозиторијум са структуром базираном на часовима
Свакa фасцикла часа садржи 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

Подешавање Quiz App-а (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Покрени сервер за развој
npm run build      # Направи продукциону верзију
npm run lint       # Покрени ESLint

Bank Project API (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Покрени API сервер
npm run lint       # Покрени ESLint
npm run format     # Форматирај са Prettier-ом

Пројекти Browser Extension-а

cd 5-browser-extension/solution
npm install
# Пратите упутства за учитавање проширења специфичних за прегледач

Пројекти Space Game-а

cd 6-space-game/solution
npm install
# Отворите index.html у прегледачу или користите Live Server

Chat Project (Python Backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Подеси GITHUB_TOKEN променљиву окружења
python api.py

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

За сараднике на садржају

Форк-ујте репозиторијум на ваш GitHub налог
Клонирајте свој форк локално
Креирајте нову грану за ваше измене
Урадите измене у садржају часова или примерима кода
Тестирајте све измене кода у одговарајућим фасциклама пројеката
Пошаљите pull request-ове у складу са смерницама за допринос

За ученике

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

Живи развој

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

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

Тестирање Quiz App-а

cd quiz-app
npm run lint       # Проверите проблеме у стилу кода
npm run build      # Потврдити да се изградња успешно завршава

Тестирање Bank API-ја

cd 7-bank-project/api
npm run lint       # Провери проблеме са стилом кода
node server.js     # Верификуј да сервер стартује без грешака

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

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

Провере пре слања

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

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

JavaScript

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

HTML/CSS

Семантички HTML5 елементи
Принципи респонзивног дизајна
Јасне конвенције именовања класа
Коментари који објашњавају CSS технике за ученике

Python

ПЕП 8 смернице за стил
Јасан, образовни пример кода
Типске наговештаје тамо где помажу учењу

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

Јасна хијерархија наслова
Блокови кода са навођењем језика
Везе ка додатним ресурсима
Снимци екрана и слике у images/ фасциклама
Alt текст за слике ради приступачности

Организација фајлова

Часови нумерисани узастопно (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:

cd quiz-app
npm run build      # Креира dist/ фолдер
# Реформира путем GitHub Actions радног тока на push у main

Конфигурација 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 прави production bundle-ове
Статички пројекти: нема градње, служи се фајлови директно

Смернице за Pull Request-ове

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

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

[Quiz-app] Додај нови квиз за час X
[Lesson-3] Исправи типо у терраријум пројекту
[Translation] Додај шпански превод за час 5
[Docs] Ажурирај упутства за подешавање

Обавезне провере

Пре слања PR-а:

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

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

Прихватите Microsoft CLA (аутоматска провера при првом PR-у)
Пратите Microsoft Open Source Code of Conduct
Погледајте CONTRIBUTING.md за детаљна упутства
Наведите бројеве issue-ова у опису 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": "..."
}
-->

Дебаговање и решавање проблема

Чести проблеми

Quiz app не може да се покрене:

Проверите верзију Node.js (препоручено v14+)
Обришите node_modules и package-lock.json, па покрените npm install поново
Проверите да ли порт није заузет (подразумевано: Vite користи порт 5173)

API сервер не почиње:

Проверите да ли је Node.js верзија минимум node >=10
Проверите да ли је порт заузет
Осигурајте да су све зависности инсталиране помоћу npm install

Browser extension се не учитава:

Проверите да ли еј manifest.json правилно форматиран
Прегледајте конзолу прегледача за грешке
Пратите упутства за инсталацију проширења специфична за прегледач

Проблеми са Python chat пројектом:

Осигурајте да је OpenAI пакет инсталиран: pip install openai
Проверите да ли је GITHUB_TOKEN постављен као environment var
Провера приступа 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+ језика) значи да су клонирања велика
Користите shallow clone ако радите само на садржају: 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
Токени треба да буду чувани као environment variables
Нико не сме да комитује токене или акредитиве

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

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

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

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

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

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

Активна заједница ученика и сарадника
Редовна ажурирања зависности и садржаја
Праћење issue-ова и дискусија од стране одржаваоца
Аутоматизована ажурирања превода преко GitHub Actions

Повезани ресурси

Microsoft Learn модули
Student Hub ресурси
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 - Развој browser extension-а
6-space-game/README.md - Развој игре базиране на Canvas-у
9-chat-project/README.md - AI chat асистент пројекат

Монорепо структура

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

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

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

20 KiB Raw Permalink Blame History Unescape Escape