المساهمة
أضف مشروعًا
كل مشروع واقعي هنا بدأ ملف markdown واحدًا داخل pull request لشخص ما. تسرد هذه الصفحة بالضبط ما يجب تغييره، بالترتيب، مع الأوامر التي تتحقق بها من عملك قبل إرساله.
-
تحقّق من أدواتك
قبل أي شيء، تأكد من توفر ما يحتاجه المشروع. تحتاج Node 22 أو أحدث (يُبنى الموقع به) وgit. إن لم يطبع أي أمر أدناه شيئًا، فالأداة مفقودة.
- node --version
- git --version
- تحقّق من إصدار Node وgit بالأوامر أدناه.
- إن كان Node أقدم من 22 فثبّت LTS الحالي من nodejs.org.
ما ينبغي أن تراهnode --version # v22.x or newer git --version # any recent version -
انسخ المستودع (fork)
النسخ (fork) هو نسختك الخاصة من المستودع على حسابك في GitHub. تعمل هناك، فلا شيء تفعله يمكن أن يؤثر على الموقع الحيّ.
- افتح github.com/abderrahim-lectures/python-data-analysis-course.
- اضغط زر Fork أعلى اليمين.
- اختر حسابك وجهةً.
- انتظر حتى ينتهي GitHub من النسخ.
- صار لديك نسختك الخاصة.
ما ينبغي أن تراهYour browser is on your fork, and the header says "forked from abderrahim-lectures/python-data-analysis-course". -
استنسخ نسختك (clone)
الاستنساخ ينزّل نسختك إلى جهازك لتعديل الملفات بشكل طبيعي. استنسخ نسختك لا الأصل: لا يمكنك الدفع (push) إلى الأصل.
- افتح طرفية في مجلد مشاريعك.
- نفّذ أمر الاستنساخ أدناه مع استبدال USERNAME.
- ادخل المجلد الجديد.
- ثبّت الاعتماديات.
ما ينبغي أن تراهCloning into 'python-data-analysis-course'... added 400+ packages in 30sgit clone https://github.com/YOUR-USERNAME/python-data-analysis-course.git cd python-data-analysis-course npm install -
أنشئ فرعًا
الفرع يبقي عملك منفصلًا عن main. فرع لكل مشروع، ليرى المراجع بالضبط ما غيّرته ولا يتعطل أحد أثناء المراجعة.
- اختر اسمًا قصيرًا بحروف صغيرة وشرطات.
- أنشئ الفرع وانتقل إليه بأمر واحد.
ما ينبغي أن تراهSwitched to a new branch 'add-file-organizer'git checkout -b add-file-organizer -
انسخ مشروعًا كقالب
كل صفحة مشروع ملف markdown بالهيكل نفسه. ابدأ بمشروع يعمل فعلًا لا بملف فارغ: فيه الترويسة وتحدٍّ واختبار قصير بالشكل الصحيح.
- انسخ ai-agent.md إلى اسم ملف مشروعك. اسم الملف يصبح الرابط.
ما ينبغي أن تراهsrc/content/projects/file-organizer.md is created and opens in your editor.cp src/content/projects/ai-agent.md src/content/projects/file-organizer.md -
املأ الترويسة
الترويسة هي الكتلة بين سطري --- في الأعلى. أربعة حقول مطلوبة: title وdescription وdifficulty وauthor. ترفض الاختبارات أي مشروع ينقصه أحدها.
- عدّل title: ما تعرضه البطاقة، نحو 50 حرفًا.
- عدّل description: جملة أقل من 160 حرفًا.
- اضبط difficulty: beginner أو intermediate أو advanced.
- اضبط author: معرّفك من الخطوة 9.
ما ينبغي أن تراهA frontmatter like the example below. The two --- lines must be the very first and last lines of the block.ترويسة كاملة، منسوخة من مشروع حقيقي:
--- title: "Build a File-Organizer Bot" description: "Sort a messy folder into category subfolders with a bot that plans before it moves." difficulty: "beginner" author: your-id ---انسخ مشروعًا موجودًا وعدّله. تتحقق الاختبارات من أن لكل مشروع الحقول المطلوبة، فالحقل الناقص يفشل قبل أن يراه المراجع.
-
اكتب المتن
المتن هو ما يتبعه القارئ فعلًا. كل مشاريع هذا المقرر بالشكل نفسه، ليعرف القراء أين ينظرون.
- ابدأ بعنوان # وسطر عمّا سيبنيانه.
- أضف فقرة لماذا يهم.
- أضف قائمة مرقّمة من 3 إلى 6 نتائج.
- قسّم البناء إلى خطوات بأوامر ومخرجات حقيقية.
- أضف تحدٍّ بإجابة مخفية في كتلة details.
- أضف اختبارًا قصيرًا.
ما ينبغي أن تراهA page that reads like the other project pages: introduction, numbered outcomes, step-by-step build, challenge, quiz.بداية متن مشروع حقيقي. لاحظ أنه يبيّن ما سيخرج به القارئ ثم يرقّم الخطوات:
# 📁 Build a File-Organizer Bot A folder you have been dumping things into for a year. You could sort it by hand, or write the thing that sorts it. ## 🎯 What you will do 1. Scan a folder and classify each file by extension. 2. Build a dry run: compute every move, print it, touch nothing. 3. Perform the moves, handling collisions instead of overwriting. -
أضف الشيفرة القابلة للتشغيل (اختياري)
إن كان لمشروعك شيفرة تستحق التشغيل، أعطها مجلدًا ليتمكن القراء من تشغيلها. المشاريع الشرحية يمكنها تخطي هذه الخطوة.
- أنشئ examples/<your-slug>/.
- أضف ملف شيفرتك.
- أضف README.md يشرح كيفية تشغيله.
- أضف pyproject.toml ليعمل uv run.
- Nothing here needs third-party packages unless the project genuinely requires them.
ما ينبغي أن تراهexamples/file-organizer/README.md examples/file-organizer/organizer.py examples/file-organizer/pyproject.tomlmkdir -p examples/file-organizer # add README.md, organizer.py and pyproject.toml -
وثّق نفسك
صفحة المساهمين مبنية من سجل لا من تاريخ git، فيظهر اسمك فقط إن أضفته. وهذا يتيح أيضًا توثيق طلاب بلا حساب GitHub.
- افتح src/lib/contributors.ts.
- أضف مدخلًا إلى مصفوفة CONTRIBUTORS.
- استخدم المعرّف نفسه في author.
- احفظ الملف.
ما ينبغي أن تراهYour entry in the array, exactly like the example below. The id is lowercase with hyphens and must match author exactly.مدخل واحد في src/lib/contributors.ts. المعرّف هو ما يجب أن يطابق حقل author في مشروعك:
export const CONTRIBUTORS: Contributor[] = [ { id: 'your-id', name: 'Your Name', github: 'your-handle', role: 'Wrote the file-organizer project', }, ]; -
شغّل الفحوص
هذه هي الفحوص نفسها التي تشغّلها CI. شغّلها قبل فتح طلب الدمج ليرى المراجع بناءً ناجحًا لا قائمة أخطاء.
- npm run test يتحقق من مخطط المحتوى والروابط والترجمات.
- npx tsc --noEmit يتحقق من TypeScript.
- npm run build يبني كل الصفحات، فيكشف الاستيرادات المكسورة.
ما ينبغي أن تراهTests 1743 passed (38 files). No TypeScript errors. Build complete with no failed pages.npm run test npx tsc --noEmit npm run build -
أودع وادفع
الإيداع (commit) نقطة حفظ برسالة. والدفع (push) يرسله إلى نسختك على GitHub حيث يراه طلب الدمج.
- جهّز الملفات التي غيّرتها.
- أودِع برسالة قصيرة.
- ادفع الفرع إلى نسختك.
ما ينبغي أن تراه2 files changed, 45 insertions(+) To github.com:YOUR-USERNAME/python-data-analysis-course.gitgit add src/content/projects/file-organizer.md src/lib/contributors.ts git commit -m "content: add file-organizer" git push -u origin add-file-organizer -
افتح طلب الدمج
طلب الدمج يطلب من المشرف مراجعة عملك ودمجه. صِف ما يعلّمه المشروع ولمن هو موجّه؛ فالمراجع يقرأ المحتوى لا الفرق فقط.
- اذهب إلى نسختك؛ يعرض شريط فتح طلب دمج.
- اضغط Compare and pull request.
- اكتب عنوانًا ووصفًا.
- اضغط Create pull request.
ما ينبغي أن تراهA pull request page showing your changes and the CI checks running.
الملفات التي ستعدّلها
-
src/content/projects/<your-slug>.mdمطلوبصفحة المشروع نفسها. حقول الـ frontmatter: title و description و difficulty و tags و author (معرّفك كمساهم). وكل ما بعد الـ frontmatter هو الدرس الذي يتبعه القارئ.
-
examples/<your-slug>/اختياريكود مرافق يمكن تشغيله محليًا، إن كان للمشروع كود. المشاريع التي تعلّم مفهومًا دون بناء أداة يمكنها تجاوزه.
-
src/lib/contributors.tsفقط إن كانت هذه أول مرة تظهر فيهاأضف مدخلًا بمعرّفك واسمك، واسم حسابك على GitHub إن أردت. اضبط author: <معرّفك> في صفحة مشروعك ليظهر هناك.
ما يجعل الـ pull request يُدمج أسرع
- علّم شيئًا واحدًا من أوله إلى آخره. مشروع يبني أداة صغيرة بصدق أفضل من مشروع يلمس خمس مكتبات.
- أبقِ الكود قابلًا للتشغيل. يجب أن يستطيع القارئ نسخ خطوة وتشغيلها، لا قراءتها فقط.
- اكتب قسم الأخطاء الشائعة أخيرًا، من الأخطاء التي وقعت فيها فعلًا أثناء البناء.
- لا تضف ترجمة بنفسك إلا إن كنت تتحدث اللغة فعلًا. الإنجليزية تكفي؛ والمترجمون يتولّون الباقي.