17 KiB

Raw Permalink Blame History

AGENTS.md

نظرة عامة على المشروع

هذا مستودع منهج تعليمي لتعليم أساسيات تطوير الويب للمبتدئين. المنهج هو دورة شاملة مدتها 12 أسبوعًا تم تطويرها بواسطة Microsoft Cloud Advocates، ويضم 24 درسًا عمليًا يغطي JavaScript و CSS و HTML.

المكونات الرئيسية

المحتوى التعليمي: 24 درسًا منظّمة ضمن وحدات قائمة على المشاريع
المشاريع العملية: Terrarium، لعبة الطباعة، إضافة المتصفح، لعبة الفضاء، تطبيق البنك، محرر الأكواد، ومساعد دردشة AI
اختبارات تفاعلية: 48 اختبارًا كل منها يحتوي على 3 أسئلة (تقييمات قبل وبعد الدرس)
دعم متعدد اللغات: ترجمات آلية لأكثر من 50 لغة عبر GitHub Actions
التقنيات: HTML، CSS، JavaScript، Vue.js 3، Vite، Node.js، Express، Python (لمشاريع الذكاء الاصطناعي)

الهيكلية

مستودع تعليمي به هيكلية قائمة على الدروس
يحتوي كل مجلد درس على 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 في المتصفح أو استخدم Live Server

مشروع الدردشة (خلفية Python)

cd 9-chat-project/solution/backend/python
pip install openai
# تعيين متغير البيئة GITHUB_TOKEN
python api.py

سير العمل التطويري

للمساهمين في المحتوى

افتح فورك للمستودع على حساب GitHub الخاص بك
انسخ الفورك محليًا
أنشئ فرعًا جديدًا لتغييراتك
قم بإجراء تغييرات على محتوى الدرس أو أمثلة الشفرة
اختبر أي تغييرات في الشفرة في مجلدات المشروع المعنية
قدم طلبات سحب باتباع إرشادات المساهمة

للمتعلمين

افتح فورك أو انسخ المستودع
انتقل إلى مجلدات الدروس بترتيب متسلسل
اقرأ ملفات 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       # التحقق من وجود مشكلات في نمط الكود
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

إرشادات نمط PEP 8
أمثلة شفرة واضحة وتعليمية
استخدام تلميحات النوع حيثما كان ذلك مفيدًا للتعلم

توثيق Markdown

هيكلية عناوين واضحة
كتل شفرة مع تحديد اللغة
روابط لمصادر إضافية
لقطات شاشة وصور في مجلدات images/
نص بديل للصور لتوفير إمكانية الوصول

تنظيم الملفات

ترقيم الدروس بتسلسل (1-getting-started-lessons، 2-js-basics، إلخ)
لكل مشروع مجلدات solution/ وغالبًا start/ أو your-work/
تخزين الصور في مجلدات images/ الخاصة بكل درس
الترجمات ضمن هيكل translations/{language-code}/

البناء والنشر

نشر تطبيق الاختبارات (Azure Static Web Apps)

تم تكوين تطبيق quiz-app للنشر عبر 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] إصلاح خطأ مطبعي في مشروع terrarium
[Translation] إضافة ترجمة إسبانية للدرس 5
[Docs] تحديث تعليمات الإعداد

الفحوصات المطلوبة

قبل تقديم طلب السحب:

جودة الشفرة:
- شغّل npm run lint في مجلدات المشاريع المتأثرة
- أصلح جميع أخطاء وتحذيرات اللينتر
التحقق من البناء:
- شغّل npm run build إذا كان ذلك مناسبًا
- تأكد من عدم وجود أخطاء في البناء
التحقق من الروابط:
- اختبر جميع روابط markdown
- تحقق من عمل مراجع الصور
مراجعة المحتوى:
- تدقيق إملائي ونحوي
- تأكد من صحة وأسلوب أمثلة الشفرة التعليمية
- تحقق من دقة الترجمات والمحافظة على المعنى الأصلي

متطلبات المساهمة

الموافقة على اتفاقية Microsoft CLA (فحص تلقائي عند أول PR)
الالتزام بـ ميثاق السلوك المصدر المفتوح من Microsoft
انظر CONTRIBUTING.md للإرشادات التفصيلية
أدرج أرقام القضايا في وصف طلب السحب إذا وجد

عملية المراجعة

يتم مراجعة طلبات السحب من قبل الصيانة والمجتمع
تُعطى أولوية لوضوح المحتوى التعليمي
يجب أن تتبع أمثلة الشفرة أفضل الممارسات الحالية
تُراجع الترجمات للدقة والملائمة الثقافية

نظام الترجمة

الترجمة الآلية

يستخدم 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

عدم تقديم 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 build)

اعتبارات الأمان

متغيرات البيئة

يجب ألا تُخزّن مفاتيح API في المستودع
استخدم ملفات .env (مودّجة بالفعل في .gitignore)
وثّق متغيرات البيئة المطلوبة في ملفات README الخاصة بالمشاريع

مشاريع Python

استخدم بيئات افتراضية: python -m venv venv
حافظ على تحديث التبعيات
يجب أن يمتلك رموز GitHub الحد الأدنى من الأذونات المطلوبة

وصول نماذج GitHub

تتطلب رموز وصول شخصية (PAT) لنماذج GitHub
يجب تخزين الرموز كمتغيرات بيئية
لا تلتزم الرموز أو بيانات الاعتماد في المستودع

ملاحظات إضافية

الجمهور المستهدف

مبتدئون تمامًا في تطوير الويب
الطلاب والمتعلمون الذاتيّون
المعلمون الذين يستخدمون المنهج في الفصول الدراسية
المحتوى مصمم ليكون سهل الوصول ويُبنى المهارات تدريجيًا

الفلسفة التعليمية

نهج التعلم بالمشاريع
اختبارات متكررة للمعرفة (الاختبارات)
تمارين ترميز عملية
أمثلة تطبيق من الواقع
التركيز على الأساسيات قبل الأُطُر

صيانة المستودع

مجتمع نشط من المتعلمين والمساهمين
تحديثات منتظمة للتبعيات والمحتوى
متابعة القضايا والمناقشات من قبل الصيانة
تحديثات الترجمة آلية عبر GitHub Actions

الموارد ذات الصلة

وحدات Microsoft Learn
موارد Student Hub
GitHub Copilot يُوصى به للمتعلمين
دورات إضافية: الذكاء الاصطناعي التوليدي، علوم البيانات، تعلم الآلة، مناهج إنترنت الأشياء متاحة

العمل مع مشاريع محددة

للحصول على تعليمات مفصلة حول المشاريع الفردية، راجع ملفات 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

هيكلية Monorepo

على الرغم من أنه ليس monorepo تقليدي، يحتوي هذا المستودع على مشاريع مستقلة متعددة:

كل درس قائم بذاته
المشاريع لا تشترك في التبعيات
يمكنك العمل على مشاريع فردية بدون التأثير على الآخرين
انسخ المستودع بالكامل للحصول على تجربة المنهج الكامل

تنويه:
تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية Co-op Translator. بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الموثوق والمعتمد. للمعلومات الحساسة أو الحيوية، يُنصح بالاعتماد على ترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة.

17 KiB Raw Permalink Blame History