الـ Pull Requests ومراجعة الكود

حين تعمل وحدك، دمج الفرع مجرد أمر. أما في الفريق فهو حوار: يقرأ شخص آخر التغيير، ويطرح الأسئلة، ويكتشف الخطأ الذي لم تره، وبعد ذلك فقط يصل إلى main. والـ pull request (طلب الدمج) على GitHub هو المكان الذي يجري فيه هذا الحوار. وحتى في موقع شخصي تعمل عليه وحدك يستحق الاستخدام، لأنك بعد بضعة دروس ستربط به فحوصًا آلية، ولأن أصحاب العمل ينظرون إلى طريقة عملك، لا إلى ما بنيته فقط.

من الفرع إلى الـ pull request

بنيت مرشّحًا (filter) لصفحة المشاريع على فرع ورفعته:

git switch -c projects-filter
# …commits…
git push -u origin projects-filter

يتضمّن ناتج الرفع رابطًا: Create a pull request for 'projects-filter' on GitHub by visiting: https://github.com/maya-okafor/portfolio/pull/new/projects-filter. افتحه، أو انقر شريط “Compare & pull request” في صفحة الـ repository. تحقّق من محدّدي الفرعين: base هو المكان الذي يجب أن يذهب إليه العمل (main)، و compare هو فرعك.

ومع GitHub CLI، يطلب gh pr create عنوانًا ونصًا في الطرفية، و gh pr create --fill يستخدم رسائل الـ commits الخاصة بك.

وإن لم يكن العمل جاهزًا لكنك تريد ملاحظات مبكرة، فافتحه كـ draft pull request (مسوّدة). لا يمكن دمجه حتى تعلّمه بأنه جاهز، وهو يخبر المراجعين أن ينظروا إلى الاتجاه العام لا إلى التفاصيل.

اكتب وصفًا يستطيع الناس التصرّف بناءً عليه

العنوان يقول ما يفعله التغيير: “Add tag filter to projects page”. والنص يجيب عن ثلاثة أسئلة:

## What
Adds tag buttons above the project grid; clicking one hides cards without that tag.

## Why
The grid has 14 projects now and visitors asked for a way to find the React ones.

## How to check
1. Open projects.html
2. Click "React": only 5 cards remain
3. Click "All": all 14 return

Closes #12

أضف لقطة شاشة لأي شيء مرئي؛ ويمكنك لصق الصور مباشرة في المربّع. السطر الأخير يستخدم كلمة إغلاق مفتاحية: حين يُدمج هذا الـ pull request في الفرع الافتراضي، يُغلق الـ issue رقم 12 تلقائيًا ويرتبط الاثنان ببعضهما. وتعمل Fixes و Resolves أيضًا.

المراجعة

يفتح المراجِع تبويب Files changed، الذي يعرض الـ diff بين فرعك وقاعدته. يستطيع التعليق على أي سطر، أو تحديد عدة أسطر لتعليق أشمل، أو كتابة suggestion (اقتراح): بديل مقترح تستطيع تطبيقه بنقرة واحدة كـ commit. وحين ينتهي، يرسل مراجعته بإحدى الحالات Comment أو Approve أو Request changes.

للردّ لا تفتح أي شيء جديد. نفّذ التغييرات محليًا، وأنشئ commit، وارفعه إلى الفرع نفسه:

git commit -am "Rename filter class to project-filter"
git push

يتحدّث الـ pull request، ويرى المراجِع فقط ما تغيّر منذ مراجعته الأخيرة. ردّ على كل تعليق، وأغلق النقاشات المحسومة (resolve)، واطلب نظرة أخرى.

أبقِ الـ pull requests صغيرة. حين يبقى التغيير دون 400 سطر تقريبًا يستطيع المراجِع أن يفكّر فعلًا في كل سطر؛ أما الـ pull request ذو الألفي سطر فيُمرّ عليه سريعًا ويُوافَق عليه. وإن كانت الـ feature كبيرة، فقسّمها إلى سلسلة من الـ pull requests يترك كل منها الموقع يعمل.

الدمج: ثلاثة أزرار، ثلاثة سجلّات

بعد الموافقة، يعرض زر الدمج حتى ثلاث طرق، وتستطيع إعدادات الـ repository تقييدها:

• Create a merge commit: كل الـ commits الخاصة بك مع merge commit، مثل git merge --no-ff.
• Squash and merge: الـ commits الخاصة بك مجمّعة في commit واحد جديد على main، يحمل عنوان الـ pull request.
• Rebase and merge: الـ commits الخاصة بك يُعاد تشغيلها على main واحدًا تلو الآخر، دون merge commit.

الـ Squash and merge خيار افتراضي شائع للـ pull requests الصغيرة: يحصل main على commit نظيف واحد لكل تغيير، وتختفي الـ commits من نوع “fix typo”. أما الـ merge commits فتناسب الأعمال الأكبر التي تروي فيها الـ commits المنفردة قصة مفيدة. اختر واحدة لكل repository والتزم بها.

بعد الدمج، انقر Delete branch على GitHub، ثم رتّب الأمور محليًا:

git switch main
git pull
git branch -D projects-filter

لماذا -D وليس -d؟ بعد دمج بطريقة squash أو rebase، لا تكون الـ commits الأصلية في فرعك أسلافًا لـ main (فقد أنشأ GitHub commits جديدة)، لذا يظن -d أن العمل لم يُدمج. وبمجرد أن يعرض GitHub الـ pull request على أنه مدموج، يصبح -D آمنًا.

الانتقال إلى pull request شخص آخر لاختباره أمر واحد مع الـ CLI: gh pr checkout 14. في الدرس التالي ستستخدم بقية أدوات التعاون في GitHub: الـ issues والـ projects لتخطيط العمل، والـ forks للمساهمة في repositories لا تملكها.