PyDA Course

المساهمة

أضف مشروعًا

كل مشروع واقعي هنا بدأ ملف markdown واحدًا داخل pull request لشخص ما. تسرد هذه الصفحة بالضبط ما يجب تغييره، بالترتيب، مع الأوامر التي تتحقق بها من عملك قبل إرساله.

مخطط: الملفات الثلاثة التي يحتاجها مشروع جديد. الخطوة 1 ملف markdown مطلوب في src/content/projects. الخطوة 2 مجلد examples اختياري. الخطوة 3 مدخل مطلوب في src/lib/contributors.ts.
الملفات الثلاثة. الأوسط فقط اختياري.
  1. تحقّق من أدواتك

    قبل أي شيء، تأكد من توفر ما يحتاجه المشروع. تحتاج Node 22 أو أحدث (يُبنى الموقع به) وgit. إن لم يطبع أي أمر أدناه شيئًا، فالأداة مفقودة.

    1. node --version
    2. git --version
    3. تحقّق من إصدار Node وgit بالأوامر أدناه.
    4. إن كان Node أقدم من 22 فثبّت LTS الحالي من nodejs.org.
    ما ينبغي أن تراه
    node --version   # v22.x or newer
    git --version    # any recent version
  2. انسخ المستودع (fork)

    النسخ (fork) هو نسختك الخاصة من المستودع على حسابك في GitHub. تعمل هناك، فلا شيء تفعله يمكن أن يؤثر على الموقع الحيّ.

    1. افتح github.com/abderrahim-lectures/python-data-analysis-course.
    2. اضغط زر Fork أعلى اليمين.
    3. اختر حسابك وجهةً.
    4. انتظر حتى ينتهي GitHub من النسخ.
    5. صار لديك نسختك الخاصة.
    ما ينبغي أن تراه
    Your browser is on your fork, and the header says "forked from abderrahim-lectures/python-data-analysis-course".
  3. استنسخ نسختك (clone)

    الاستنساخ ينزّل نسختك إلى جهازك لتعديل الملفات بشكل طبيعي. استنسخ نسختك لا الأصل: لا يمكنك الدفع (push) إلى الأصل.

    1. افتح طرفية في مجلد مشاريعك.
    2. نفّذ أمر الاستنساخ أدناه مع استبدال USERNAME.
    3. ادخل المجلد الجديد.
    4. ثبّت الاعتماديات.
    ما ينبغي أن تراه
    Cloning into 'python-data-analysis-course'...
    added 400+ packages in 30s
    git clone https://github.com/YOUR-USERNAME/python-data-analysis-course.git
    cd python-data-analysis-course
    npm install
  4. أنشئ فرعًا

    الفرع يبقي عملك منفصلًا عن main. فرع لكل مشروع، ليرى المراجع بالضبط ما غيّرته ولا يتعطل أحد أثناء المراجعة.

    1. اختر اسمًا قصيرًا بحروف صغيرة وشرطات.
    2. أنشئ الفرع وانتقل إليه بأمر واحد.
    ما ينبغي أن تراه
    Switched to a new branch 'add-file-organizer'
    git checkout -b add-file-organizer
  5. انسخ مشروعًا كقالب

    كل صفحة مشروع ملف markdown بالهيكل نفسه. ابدأ بمشروع يعمل فعلًا لا بملف فارغ: فيه الترويسة وتحدٍّ واختبار قصير بالشكل الصحيح.

    1. انسخ 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
  6. املأ الترويسة

    الترويسة هي الكتلة بين سطري --- في الأعلى. أربعة حقول مطلوبة: title وdescription وdifficulty وauthor. ترفض الاختبارات أي مشروع ينقصه أحدها.

    1. عدّل title: ما تعرضه البطاقة، نحو 50 حرفًا.
    2. عدّل description: جملة أقل من 160 حرفًا.
    3. اضبط difficulty: beginner أو intermediate أو advanced.
    4. اضبط 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
    ---

    انسخ مشروعًا موجودًا وعدّله. تتحقق الاختبارات من أن لكل مشروع الحقول المطلوبة، فالحقل الناقص يفشل قبل أن يراه المراجع.

  7. اكتب المتن

    المتن هو ما يتبعه القارئ فعلًا. كل مشاريع هذا المقرر بالشكل نفسه، ليعرف القراء أين ينظرون.

    1. ابدأ بعنوان # وسطر عمّا سيبنيانه.
    2. أضف فقرة لماذا يهم.
    3. أضف قائمة مرقّمة من 3 إلى 6 نتائج.
    4. قسّم البناء إلى خطوات بأوامر ومخرجات حقيقية.
    5. أضف تحدٍّ بإجابة مخفية في كتلة details.
    6. أضف اختبارًا قصيرًا.
    ما ينبغي أن تراه
    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.
  8. أضف الشيفرة القابلة للتشغيل (اختياري)

    إن كان لمشروعك شيفرة تستحق التشغيل، أعطها مجلدًا ليتمكن القراء من تشغيلها. المشاريع الشرحية يمكنها تخطي هذه الخطوة.

    1. أنشئ examples/<your-slug>/.
    2. أضف ملف شيفرتك.
    3. أضف README.md يشرح كيفية تشغيله.
    4. أضف pyproject.toml ليعمل uv run.
    5. 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.toml
    mkdir -p examples/file-organizer
    # add README.md, organizer.py and pyproject.toml
  9. وثّق نفسك

    صفحة المساهمين مبنية من سجل لا من تاريخ git، فيظهر اسمك فقط إن أضفته. وهذا يتيح أيضًا توثيق طلاب بلا حساب GitHub.

    1. افتح src/lib/contributors.ts.
    2. أضف مدخلًا إلى مصفوفة CONTRIBUTORS.
    3. استخدم المعرّف نفسه في author.
    4. احفظ الملف.
    ما ينبغي أن تراه
    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',
      },
    ];
  10. شغّل الفحوص

    هذه هي الفحوص نفسها التي تشغّلها CI. شغّلها قبل فتح طلب الدمج ليرى المراجع بناءً ناجحًا لا قائمة أخطاء.

    1. npm run test يتحقق من مخطط المحتوى والروابط والترجمات.
    2. npx tsc --noEmit يتحقق من TypeScript.
    3. 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
  11. أودع وادفع

    الإيداع (commit) نقطة حفظ برسالة. والدفع (push) يرسله إلى نسختك على GitHub حيث يراه طلب الدمج.

    1. جهّز الملفات التي غيّرتها.
    2. أودِع برسالة قصيرة.
    3. ادفع الفرع إلى نسختك.
    ما ينبغي أن تراه
    2 files changed, 45 insertions(+)
    To github.com:YOUR-USERNAME/python-data-analysis-course.git
    git 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
  12. افتح طلب الدمج

    طلب الدمج يطلب من المشرف مراجعة عملك ودمجه. صِف ما يعلّمه المشروع ولمن هو موجّه؛ فالمراجع يقرأ المحتوى لا الفرق فقط.

    1. اذهب إلى نسختك؛ يعرض شريط فتح طلب دمج.
    2. اضغط Compare and pull request.
    3. اكتب عنوانًا ووصفًا.
    4. اضغط Create pull request.
    ما ينبغي أن تراه
    A pull request page showing your changes and the CI checks running.
مخطط: كيف تنتقل المساهمة. انسخ المستودع (fork) ثم استنسخه محليًا، وأنشئ فرعًا، ثم commit وpush، ثم افتح طلب دمج. عند الدمج في main يُنشر الموقع تلقائيًا.
أين يُنفَّذ كل أمر. الخطوات من الثانية إلى الرابعة تجري على جهازك.

الملفات التي ستعدّلها

  • src/content/projects/<your-slug>.md مطلوب

    صفحة المشروع نفسها. حقول الـ frontmatter: title و description و difficulty و tags و author (معرّفك كمساهم). وكل ما بعد الـ frontmatter هو الدرس الذي يتبعه القارئ.

  • examples/<your-slug>/ اختياري

    كود مرافق يمكن تشغيله محليًا، إن كان للمشروع كود. المشاريع التي تعلّم مفهومًا دون بناء أداة يمكنها تجاوزه.

  • src/lib/contributors.ts فقط إن كانت هذه أول مرة تظهر فيها

    أضف مدخلًا بمعرّفك واسمك، واسم حسابك على GitHub إن أردت. اضبط author: <معرّفك> في صفحة مشروعك ليظهر هناك.

ما يجعل الـ pull request يُدمج أسرع

  • علّم شيئًا واحدًا من أوله إلى آخره. مشروع يبني أداة صغيرة بصدق أفضل من مشروع يلمس خمس مكتبات.
  • أبقِ الكود قابلًا للتشغيل. يجب أن يستطيع القارئ نسخ خطوة وتشغيلها، لا قراءتها فقط.
  • اكتب قسم الأخطاء الشائعة أخيرًا، من الأخطاء التي وقعت فيها فعلًا أثناء البناء.
  • لا تضف ترجمة بنفسك إلا إن كنت تتحدث اللغة فعلًا. الإنجليزية تكفي؛ والمترجمون يتولّون الباقي.