|
|
# 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
|
|
|
|
|
|
## פקודות התקנה
|
|
|
|
|
|
המאגר מיועד בעיקר לצריכת תוכן חינוכי. לעבודה עם פרויקטים ספציפיים:
|
|
|
|
|
|
### התקנת המאגר הראשי
|
|
|
|
|
|
```bash
|
|
|
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
|
|
|
cd Web-Dev-For-Beginners
|
|
|
```
|
|
|
|
|
|
### התקנת אפליקציית החידונים (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
|
|
|
```
|
|
|
|
|
|
### פרויקט צ׳אט (Backend בפייתון)
|
|
|
|
|
|
```bash
|
|
|
cd 9-chat-project/solution/backend/python
|
|
|
pip install openai
|
|
|
# הגדר את משתנה הסביבה GITHUB_TOKEN
|
|
|
python api.py
|
|
|
```
|
|
|
|
|
|
## זרימת עבודה בפיתוח
|
|
|
|
|
|
### עבור תורמים לתוכן
|
|
|
|
|
|
1. **צור Fork למאגר** לחשבון ה-GitHub שלך
|
|
|
2. **שכפל את ה-Fork** במחשב המקומי שלך
|
|
|
3. **צור סניף חדש** לשינויים שלך
|
|
|
4. בצע שינויים בתוכן השיעורים או בדוגמאות הקוד
|
|
|
5. בדוק כל שינויי קוד בתיקיות הפרויקט הרלוונטיות
|
|
|
6. הגש בקשות משיכה בהתאם להנחיות התרומה
|
|
|
|
|
|
### עבור הלומדים
|
|
|
|
|
|
1. צור Fork או שכפל את המאגר
|
|
|
2. עבור רצוף בין תיקיות השיעורים
|
|
|
3. קרא את קבצי README עבור כל שיעור
|
|
|
4. השלם חידוני לפני שיעור בכתובת https://ff-quizzes.netlify.app/web/
|
|
|
5. עבד על דוגמאות הקוד בתיקיות השיעורים
|
|
|
6. השלם משימות ואתגרים
|
|
|
7. בצע חידוני לאחר השיעור
|
|
|
|
|
|
### פיתוח חי
|
|
|
|
|
|
- **תיעוד**: הפעל `docsify serve` בתיקיית השורש (פורט 3000)
|
|
|
- **אפליקציית חידונים**: הפעל `npm run dev` בתיקיית quiz-app
|
|
|
- **פרויקטים**: השתמש ב-VS Code Live Server להפעלת פרויקטים HTML
|
|
|
- **פרויקטי API**: הפעל `npm start` בתיקיות ה-API המתאימות
|
|
|
|
|
|
## הוראות בדיקה
|
|
|
|
|
|
### בדיקת אפליקציית חידונים
|
|
|
|
|
|
```bash
|
|
|
cd quiz-app
|
|
|
npm run lint # בדוק שגיאות בסגנון הקוד
|
|
|
npm run build # אמת שהבניין מצליח
|
|
|
```
|
|
|
|
|
|
### בדיקת API של הבנק
|
|
|
|
|
|
```bash
|
|
|
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
|
|
|
|
|
|
- קווי הנחיה בסגנון PEP 8
|
|
|
- דוגמאות קוד ברורות וחינוכיות
|
|
|
- רמזי טיפוס כאשר זה מועיל ללמידה
|
|
|
|
|
|
### תיעוד ב-Markdown
|
|
|
|
|
|
- היררכיית כותרות ברורה
|
|
|
- בלוקי קוד עם הגדרת שפה
|
|
|
- קישורים למשאבים נוספים
|
|
|
- צילומי מסך ותמונות בתיקיות `images/`
|
|
|
- טקסט חלופי לתמונות לנגישות
|
|
|
|
|
|
### ארגון קבצים
|
|
|
|
|
|
- שיעורים ממוספרים בסדר (1-getting-started-lessons, 2-js-basics וכו׳)
|
|
|
- לכל פרויקט תיקיות `solution/` ולעיתים `start/` או `your-work/`
|
|
|
- תמונות מאוחסנות בתיקיות `images/` ספציפיות לשיעור
|
|
|
- תרגומים במבנה `translations/{language-code}/`
|
|
|
|
|
|
## בנייה ופריסה
|
|
|
|
|
|
### פריסת אפליקציית חידונים (Azure Static Web Apps)
|
|
|
|
|
|
אפליקציית החידונים מוגדרת לפריסה בשירות Azure Static Web Apps:
|
|
|
|
|
|
```bash
|
|
|
cd quiz-app
|
|
|
npm run build # יוצרת את התיקיה dist/
|
|
|
# מבצעת פריסה דרך זרימת עבודה של GitHub Actions בעת דחיפה לענף main
|
|
|
```
|
|
|
|
|
|
הגדרות 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 # יצירת PDF מ-docs
|
|
|
```
|
|
|
|
|
|
### תיעוד 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` בתיקיות הפרויקט הרלוונטיות
|
|
|
- תקן כל שגיאה או אזהרה
|
|
|
|
|
|
2. **אימות בנייה**:
|
|
|
- הפעל `npm run build` אם נדרש
|
|
|
- וודא שאין שגיאות בנייה
|
|
|
|
|
|
3. **אימות קישורים**:
|
|
|
- בדוק את כל קישורי ה-markdown
|
|
|
- ודא שהקישורים לתמונות תקינים
|
|
|
|
|
|
4. **סקירת תוכן**:
|
|
|
- ערוך הגהה לאיות ותחביר
|
|
|
- ודא שהדוגמאות נכונות וחינוכיות
|
|
|
- וודא שהתרגומים שומרים על המשמעות המקורית
|
|
|
|
|
|
### דרישות לתרומה
|
|
|
|
|
|
- אישור CLA של מיקרוסופט (בדיקה אוטומטית בעת PR ראשון)
|
|
|
- עקוב אחר [קוד ההתנהגות של Microsoft Open Source](https://opensource.microsoft.com/codeofconduct/)
|
|
|
- עיין בקובץ [CONTRIBUTING.md](./CONTRIBUTING.md) להנחיות מפורטות
|
|
|
- התייחס למספרי נושאים בתיאור ה-PR אם רלוונטי
|
|
|
|
|
|
### תהליך סקירה
|
|
|
|
|
|
- בקשות משיכה נסקרות על ידי מנהלים והקהילה
|
|
|
- דגש על בהירות חינוכית
|
|
|
- דוגמאות קוד צריכות לעקוב אחר נהלי עבודה מומלצים
|
|
|
- תרגומים נבדקים לדיוק והתאמה תרבותית
|
|
|
|
|
|
## מערכת תרגום
|
|
|
|
|
|
### תרגום אוטומטי
|
|
|
|
|
|
- משתמש ב-GitHub Actions עם זרימת עבודה co-op-translator
|
|
|
- מתרגם ל-50+ שפות אוטומטית
|
|
|
- קבצי מקור בתיקיות הראשיות
|
|
|
- קבצי תרגום בתיקיות `translations/{language-code}/`
|
|
|
|
|
|
### הוספת שיפורים ידניים לתרגום
|
|
|
|
|
|
1. אתר את הקובץ בתיקיית `translations/{language-code}/`
|
|
|
2. בצע שיפורים תוך שמירת המבנה
|
|
|
3. וודא שדוגמאות הקוד נשארות פונקציונליות
|
|
|
4. בדוק כל תוכן חידונים מותאם
|
|
|
|
|
|
### מטא-דאטה לתרגומים
|
|
|
|
|
|
קבצי התרגום כוללים כותרת מטא-דאטה:
|
|
|
```markdown
|
|
|
<!--
|
|
|
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 מעוצב כראוי
|
|
|
- בדוק בלוג הדפדפן לשגיאות
|
|
|
- עקוב אחר הוראות ההתקנה הספציפיות לדפדפן
|
|
|
|
|
|
**בעיות בפרויקט צ׳אט בפייתון**:
|
|
|
- ודא שהחבילה OpenAI מותקנת: `pip install openai`
|
|
|
- בדוק שהמשתנה הסביבתי GITHUB_TOKEN מוגדר
|
|
|
- בדוק הרשאות גישה למודלים דרך GitHub
|
|
|
|
|
|
**Docsify לא מגישה תיעוד**:
|
|
|
- התקן docsify-cli גלובלית: `npm install -g docsify-cli`
|
|
|
- הפעל מהתיקייה השורשית של המאגר
|
|
|
- ודא שקיים הקובץ `docs/_sidebar.md`
|
|
|
|
|
|
### טיפים לסביבת פיתוח
|
|
|
|
|
|
- השתמש ב-VS Code עם הרחבת Live Server לפרויקטים ב-HTML
|
|
|
- התקן את ההרחבות ESLint ו-Prettier לעיצוב עקבי
|
|
|
- השתמש בכלי הפיתוח של הדפדפן לניפוי שגיאות ב-JavaScript
|
|
|
- לפרויקטים ב-Vue התקן Vue DevTools בדפדפן
|
|
|
|
|
|
### שיקולי ביצועים
|
|
|
|
|
|
- מספר גדול של קבצי תרגום (50+ שפות) גורם לשכפולים מלאים להיות כבדים
|
|
|
- השתמש בשכפול רדוד אם עובד רק על תוכן: `git clone --depth 1`
|
|
|
- וחרג תוצאות חיפוש מתרגומים בעת עבודה על תוכן באנגלית
|
|
|
- תהליכי בנייה עלולים להיות איטיים בהרצה הראשונה (npm install, בניית Vite)
|
|
|
|
|
|
## שיקולי אבטחה
|
|
|
|
|
|
### משתני סביבה
|
|
|
|
|
|
- אסור לשמור מפתחות API במאגר
|
|
|
- השתמש בקבצי `.env` (כבר ב-.gitignore)
|
|
|
- תעד משתני סביבה נדרשים בקבצי README של הפרויקטים
|
|
|
|
|
|
### פרויקטים בפייתון
|
|
|
|
|
|
- השתמש בסביבות וירטואליות: `python -m venv venv`
|
|
|
- שמור על עדכון התלויות
|
|
|
- אסימונים של GitHub צריכים להיות עם הרשאות מינימליות
|
|
|
|
|
|
### גישה למודלים של GitHub
|
|
|
|
|
|
- דרושים 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) מומלץ ללומדים
|
|
|
- קורסים נוספים: AI גנרטיבי, מדעי נתונים, למידת מכונה, 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
|
|
|
|
|
|
### מבנה מונורפו
|
|
|
|
|
|
למרות שאינו מונורפו מסורתי, מאגר זה מכיל מספר פרויקטים עצמאיים:
|
|
|
- כל שיעור עצמאי
|
|
|
- הפרויקטים אינם חולקים תלותיות
|
|
|
- עבוד על פרויקטים נפרדים ללא השפעה על אחרים
|
|
|
- שכפל את כל המאגר לחוויית תוכנית לימודים מלאה
|
|
|
|
|
|
---
|
|
|
|
|
|
<!-- CO-OP TRANSLATOR DISCLAIMER START -->
|
|
|
**כתב ויתור**:
|
|
|
מסמך זה תורגם באמצעות שירות תרגום מבוסס בינה מלאכותית [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש להיות מודעים לכך שתירגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. המסמך המקורי בשפת המקור שלו הוא המקור הסמכותי. למידע קריטי מומלץ להשתמש בתרגום מקצועי של אדם. אנו לא אחראים לכל אי-הבנה או פרשנות שגויה הנובעת משימוש בתרגום זה.
|
|
|
<!-- CO-OP TRANSLATOR DISCLAIMER END --> |
