ایک ناکام GitHub PR کو کیسے ٹھیک کریں: ڈیبگنگ CI، Lint Errors، اور Build Errors مرحلہ وار

بہت سے گائیڈ بتاتے ہیں کہ مسلسل انضمام کی پائپ لائن کیسے ترتیب دی جائے، لیکن کچھ ہی آپ کو دکھاتے ہیں کہ جب متعدد پرتوں میں مسائل پیدا ہوتے ہیں تو ڈیبگ کیسے کریں۔

اوپن سورس میں تعاون کرتے وقت یہ ایک عام تجربہ ہے۔ آپ ایک چھوٹی سی تبدیلی کرتے ہیں، پل کی درخواست کھولتے ہیں، اور اچانک سب کچھ ناکام ہوجاتا ہے۔

اسے ایک بار نہیں بلکہ کئی بار چیک کریں۔

لنٹ کی خرابی
YAML کی توثیق کے مسائل
تعمیر ناکام ہوگئی
تعیناتی ناکام ہو گئی۔

اس سے بھی زیادہ الجھن کی بات یہ ہے کہ غلطیاں آپ کے کوڈ بیس کے ان حصوں میں ظاہر ہو سکتی ہیں جن میں آپ نے ترمیم نہیں کی ہے۔

اس مضمون میں، آپ ان مسائل کو مرحلہ وار ڈیبگ کرنے کا طریقہ سیکھیں گے۔ مقصد نہ صرف ایک پل کی درخواست میں ترمیم کرنا ہے بلکہ یہ بھی سمجھنا ہے کہ CI سسٹم تبدیلیوں کی توثیق کیسے کرتا ہے۔

یہ گائیڈ اوپن سورس دستاویزات کے پروجیکٹس میں تعاون کرتے ہوئے حاصل کردہ حقیقی دنیا کے ڈیبگنگ کے تجربے پر مبنی ہے۔

یہ مثال ایک دستاویزی پروجیکٹ کی ہے، لیکن ڈیبگنگ ورک فلو CI پائپ لائنز، لنٹنگ ٹولز، اور خودکار تعمیرات کا استعمال کرتے ہوئے بہت سے ذخیروں پر لاگو ہوتا ہے۔

اشاریہ:

شرائط

اس گائیڈ پر عمل کرنے کے لیے آپ کو ضرورت ہو گی:

اپنی CI پائپ لائن کو سمجھیں (اصل میں کیا ہو رہا ہے)

بہت سے پروجیکٹس میں، آپ کو CI/CD اصطلاحات نظر آئیں گی، جس کا مطلب ہے مسلسل انضمام اور مسلسل تعیناتی (یا ڈیلیوری)۔

یہ گائیڈ خاص طور پر CI حصے پر توجہ مرکوز کرے گا، یعنی مسلسل انضمام۔ یہ ایک خودکار چیک کی نمائندگی کرتا ہے جو اس وقت چلتا ہے جب آپ کوڈ کو دباتے ہیں یا پل کی درخواست کھولتے ہیں۔ یہ چیک تبدیلیوں کی توثیق کرتے ہیں اس سے پہلے کہ وہ مین کوڈ بیس میں ضم ہو جائیں۔

دوسری طرف، مسلسل تعیناتی/ڈیلیوری (سی ڈی)، عام طور پر ایسے کاموں کو سنبھالتی ہے جو چیک پاس ہونے کے بعد ہوتے ہیں، جیسے کہ کسی درخواست کو تعینات کرنا۔

اس گائیڈ میں ڈیبگ کیے گئے زیادہ تر مسائل CI مرحلے کے دوران ہوتے ہیں، اس لیے ان اختلافات کو سمجھنا ضروری ہے۔

زیادہ تر ذخیرے پل کی درخواست کھولتے وقت کئی خودکار چیک چلاتے ہیں۔

linting آلہ فارمیٹنگ کے اصول لاگو کریں (جیسے مارک ڈاؤن لِنٹ، یاملِنٹ)
سسٹم کی تعمیر (مثال کے طور پر mdBook) ساخت کی تصدیق کرتا ہے اور آؤٹ پٹ تیار کرتا ہے۔
تعیناتی چیک کریں۔ (مثلاً Netlify) اس بات کو یقینی بنانے کے لیے کہ سائٹ بنائی اور ڈیلیور کی جا سکتی ہے۔
کنٹرولر انضمام (مثال کے طور پر جوار) منظوری کی پالیسیوں کو نافذ کرتا ہے۔

یاد رکھنے کے لیے اہم نکات: CI سسٹمز ہیں۔ کمٹ میں فائلوں کا مکمل سیٹ، یہ صرف وہ لائنیں نہیں ہیں جو آپ نے تبدیل کی ہیں۔

CI پائپ لائن پل کی درخواستوں کو کیسے ہینڈل کرتی ہے۔

جب آپ کوڈ کو دباتے ہیں یا پل کی درخواست کھولتے ہیں، تو CI پائپ لائن ترتیب وار متعدد چیک چلاتی ہے۔

آئیے تصور کریں کہ یہ چیک ایک عام CI پائپ لائن میں کیسے جڑتے ہیں۔

تصویر: آسان سی آئی پائپ لائن یہ دکھا رہی ہے کہ کس طرح لنٹنگ، تعمیر، اور تعیناتی کی تصدیق ترتیب وار چلتی ہے۔

مندرجہ بالا خاکہ فیڈ بیک لوپ کے ساتھ ایک ترتیب وار CI پائپ لائن دکھاتا ہے۔ اگر کسی بھی مرحلے پر کوئی خرابی واقع ہوتی ہے، تو آپ کو جاری رکھنے سے پہلے مسئلہ کو حل کرنا ہوگا۔

آئیے تجزیہ کریں کہ یہ خاکہ کیا ظاہر کرتا ہے۔

کوڈ کو آگے بڑھا کر یا پل کی درخواست کھول کر شروع کریں۔
CI پائپ لائن خودکار چیکوں کو چلانا شروع کر دیتی ہے۔
چیک کے پہلے سیٹ میں عام طور پر ایک لنٹنگ ٹول شامل ہوتا ہے جیسے مارک ڈاؤن لِنٹ یا یاملِنٹ۔
- اگر لنٹنگ ناکام ہو جاتی ہے، تو پائپ لائن رک جاتی ہے اور آپ کو جاری رکھنے سے پہلے فارمیٹنگ کے مسائل کو حل کرنا چاہیے۔
- اگر لنٹنگ گزر جاتی ہے تو، پائپ لائن تعمیر کے مرحلے پر چلی جاتی ہے (مثال کے طور پر دستاویز پروجیکٹ میں mdBook)۔
- جب کوئی تعمیر ناکام ہو جاتی ہے، تو اس کا عام طور پر مطلب ہوتا ہے کہ کوئی ساختی مسئلہ ہے، جیسے نقلی اندراجات یا غلط حوالہ جات۔
کامیاب تعمیر کے بعد، ایک تعیناتی چیک (مثلاً Netlify Preview) چلایا جاتا ہے۔
- جب کوئی تعیناتی ناکام ہوجاتی ہے، تو مسئلہ اکثر کنفیگریشن یا بلڈ آؤٹ پٹ سے متعلق ہوتا ہے۔
تمام مراحل سے گزرنے کے بعد، آپ کی پل کی درخواست نظرثانی کے لیے تیار ہے۔

عملی ڈیبگنگ ورک فلو

مرحلہ 1: توثیق اور اجازت کے مسائل کا ازالہ کریں۔

CI کے چلنے سے پہلے توثیق کی خرابی کی وجہ سے پش ناکام ہو سکتا ہے۔

غلطی کی مثال:

refusing to allow a Personal Access Token to create or update workflow

ایسا ہوتا ہے کیونکہ GitHub کو خصوصی اجازتوں کی ضرورت ہوتی ہے اگر آپ کی کمٹ میں درج ذیل فائلیں ہوں:

.github/workflows/

کام کا مقصد ذاتی رسائی ٹوکن (PAT) کو استعمال کرتے ہوئے دوبارہ تخلیق کرنا ہے:

repo پوزیشن
workflow اجازت

مرحلہ 2: مقامی طور پر لنٹ چیک چلائیں۔

مکمل طور پر CI فیڈ بیک پر انحصار کرنا سست ہے کیونکہ آپ کو تبدیلیوں کو آگے بڑھانا ہوگا اور خامیاں ظاہر ہونے سے پہلے پائپ لائن کے چلنے کا انتظار کرنا ہوگا۔

مقامی طور پر چیک چلانے سے آپ اپنے کوڈ کو آگے بڑھانے سے پہلے فوری طور پر مسائل کو پکڑ سکتے ہیں۔

حقیقت میں، آپ کو دونوں کرنے کی ضرورت ہے:

اپنے کوڈ کی منظوری سے پہلے مقامی معائنہ کو دفاع کی اپنی پہلی لائن اور CI کو حتمی گیٹ وے سمجھیں۔

یہاں ایک مثال ہے (مارک ڈاؤن لائنٹنگ):

npm install -g markdownlint-cli2
markdownlint-cli2 docs/**/*.md

مرحلہ 3: عام مارک ڈاؤن لِنٹ کی خرابیوں کو درست کریں۔

کچھ عام مسائل جن کا آپ کو سامنا ہو سکتا ہے ان میں شامل ہیں:

1. بغیر وضاحت کے لنک

"یہاں” جیسے نان اسکرپٹ لنکس قارئین کو اس بارے میں کوئی سیاق و سباق نہیں دیتے ہیں کہ لنک کہاں لے جاتا ہے۔ یہ دستاویزات کو سمجھنا مشکل اور ناقابل رسائی بناتا ہے، خاص طور پر ان صارفین کے لیے جو اسکرین ریڈرز پر انحصار کرتے ہیں۔

لکھنے کے بجائے:

[here](https://example.com)

اس طرح وضاحتی متن استعمال کریں:

[command help documentation](https://example.com)

2. لائن کی لمبائی کی خلاف ورزی

بہت سے پروجیکٹ مختلف آلات اور ایڈیٹرز میں پڑھنے کی اہلیت کو بہتر بنانے کے لیے زیادہ سے زیادہ لائن کی لمبائی (اکثر 80 حروف کے قریب) نافذ کرتے ہیں۔

اگر کوئی لائن بہت لمبی ہے، تو آپ اسے معنی بدلے بغیر متعدد لائنوں میں تقسیم کر سکتے ہیں۔

ایسا کرنے کے لیے، قدرتی مقامات پر لکیریں توڑ دیں، جیسے کہ الفاظ کے درمیان یا اوقاف کے بعد۔ الفاظ کو نہ توڑیں یا جملے کی ساخت میں خلل نہ ڈالیں۔
مثال کے طور پر:

This is a long sentence that should be split across multiple
lines to satisfy lint rules.

3. انڈینٹیشن کے مسائل کی فہرست بنائیں

فہرست انڈینٹیشن کی خرابیاں اس وقت ہوتی ہیں جب نیسٹڈ لسٹ آئٹمز مستقل طور پر منسلک نہیں ہوتے ہیں۔ یہ فارمیٹنگ میں بدعنوانی اور لنٹنگ کی خرابیوں کا سبب بن سکتا ہے۔

اس کو روکنے کے لیے، مستقل وقفہ کاری کا استعمال کریں (عام طور پر 2 اسپیس فی لیول)۔

مثال (غلط):

- Item 1
 - Subitem

درست ورژن:

- Item 1
  - Subitem

مرحلہ 4: مارک ڈاؤن کوڈ بلاک کے اندر YAML میں ترمیم کریں۔

YAML میں فارمیٹنگ کے سخت اصول ہیں، بشمول مناسب انڈینٹیشن، کلیدی قدر کا ڈھانچہ، اور مستقل وقفہ۔

یہاں تک کہ اگر YAML مارک ڈاون کوڈ بلاک کے اندر ظاہر ہوتا ہے، تب بھی yamllint جیسے ٹولز اس کی ساخت کی توثیق کرتے ہیں۔

مثال (غلط):

metadata:
annotations:

درست ورژن:

metadata:
  annotations:
    capi.metal3.io/unhealthy: "true"

غلط مثال میں annotations یہ نیچے مناسب طریقے سے نہیں بنایا گیا ہے۔ metadataاور کلیدی قدر کا جوڑا غیر متعین ہے۔

ترمیم شدہ ورژن میں:

یہ ڈھانچہ مناسب درجہ بندی اور فارمیٹنگ کے لیے YAML کی ضروریات کو پورا کرتا ہے۔

مرحلہ 5: لنٹ پاس کرنے کے بعد تعمیراتی غلطیوں کو درست کریں۔

لنٹ چیک پاس کرنا کامیاب تعمیر کی ضمانت نہیں دیتا۔

اس کی وجہ یہ ہے کہ لنٹنگ نحو اور فارمیٹنگ پر توجہ مرکوز کرتی ہے، جبکہ تعمیراتی عمل پورے پروجیکٹ کی ساخت اور سالمیت کی تصدیق کرتا ہے۔

تعمیر میں ناکامی اکثر درج ذیل مسائل کی وجہ سے ہوتی ہے۔

نیویگیشن فائل میں ڈپلیکیٹ اندراجات ہیں۔
گمشدہ یا غلط حوالہ شدہ فائلیں۔
غلط کنفیگریشن سیٹنگز

یہاں تک کہ اگر نحو درست ہے، تعمیراتی نظام اس بات کو یقینی بناتا ہے کہ ہر چیز صحیح طریقے سے منسلک ہے۔

مثال کے طور پر، mdBook جیسے ٹول کا استعمال کرتے ہوئے ایک دستاویز پروجیکٹ میں: SUMMARY.md تعمیر ناکام ہو سکتی ہے یہاں تک کہ اگر تمام فائلیں لنٹ چیک کو پاس کرتی ہیں۔

مرحلہ 6: ڈیبگ کاسکیڈنگ CI کی خرابیاں

CI پائپ لائنیں تہہ دار ہیں۔ ایک غلطی متعدد بہاو کی خرابیوں کا سبب بن سکتی ہے۔

مثال کے طور پر، YAML انڈینٹیشن کی خرابی کا تصور کریں۔

YAML error → build fails → deploy fails → multiple checks fail

اسے ٹھیک کرنے کے لیے:

CI لاگز میں پہلے ناکام قدم کی شناخت کریں۔
براہ کرم اس مسئلے کو ٹھیک کریں۔
پائپ لائن کو دوبارہ چلائیں۔

اس مثال میں، YAML انڈینٹیشن کی غلطیاں بنیادی وجہ ہیں۔ YAML فارمیٹ میں ترمیم کرنے سے لِنٹ چیک گزر جائے گا، جس سے تعمیر کو آگے بڑھنے اور تعیناتی کا مرحلہ کامیاب ہو جائے گا۔

اس لیے پائپ لائن کی پہلی غلطی کو ہمیشہ ٹھیک کرنا ضروری ہے بجائے اس کے کہ تمام خرابیوں کو ایک ساتھ ٹھیک کرنے کی کوشش کریں۔

مرحلہ 7: CI ڈیبگ کرتے وقت گٹ کے مسائل کو ہینڈل کریں۔

اپ ڈیٹ شدہ شاخوں کے ساتھ کام کرتے وقت، آپ کو درج ذیل مسائل کا سامنا کرنا پڑ سکتا ہے:

شاخ شاخ
rebase تنازعہ
دھکا کو مسترد کریں

ان مسائل کو حل کرنے کے لیے، آپ کو عام طور پر دو طریقوں میں سے ایک کا استعمال کرتے ہوئے برانچ کو اپ ڈیٹ کرنے کی ضرورت ہے:

آپشن 1: ری بیس (تاریخ کو صاف کرنا)

git pull --rebase

ایک ریبیس آپ کی کمٹ کی تاریخ کو دوبارہ لکھتا ہے تاکہ آپ کی تبدیلیاں برانچ کے تازہ ترین ورژن کے اوپر ظاہر ہوں۔

احتیاط کے ساتھ استعمال کریں:

آپشن 2: ضم کریں (محفوظ)

git pull --no-rebase

ضم کرنے سے کمٹ کی پوری تاریخ محفوظ رہتی ہے اور دوسروں کے ساتھ کام کرتے وقت زیادہ محفوظ ہوتا ہے، لیکن اس کے نتیجے میں انضمام کے اضافی وعدے ہو سکتے ہیں۔

تبدیلیوں کو محفوظ طریقے سے دھکیلیں۔

برانچ کو اپ ڈیٹ کرنے کے بعد، آپ کو اپنی تبدیلیوں کو آگے بڑھانے کی ضرورت پڑ سکتی ہے۔

git push --force-with-lease

استعمال نہ کریں:

git push --force

کہ --force اختیارات دوسرے معاونین کے کام کو اوور رائٹ کر سکتے ہیں۔ کہ --force-with-lease آپشن زیادہ محفوظ ہے کیونکہ یہ صرف اس صورت میں آگے بڑھتا ہے جب ریموٹ برانچ غیر متوقع طور پر تبدیل نہ ہوئی ہو۔

کلیدی ٹیک ویز

CI پوری کمٹ کی توثیق کرتا ہے، نہ صرف ان مخصوص لائنوں کو جو آپ نے تبدیل کی ہیں۔
لنٹنگ اور بلڈ سسٹم مختلف اصول لاگو کرتے ہیں۔
مارک ڈاؤن کے اندر YAML ساختی طور پر درست ہونا چاہیے۔
ساختی مسائل کی وجہ سے دستاویز کی تعمیر ناکام ہو سکتی ہے۔
مقامی طور پر چیک چلانے سے ڈیبگنگ کا وقت نمایاں طور پر کم ہوجاتا ہے۔

نتیجہ

ایک ناکام پل کی درخواست کو ڈیبگ کرنا صرف نحوی غلطیوں کو ٹھیک کرنے کے بارے میں نہیں ہے۔

آپ کو یہ بھی سمجھنے کی ضرورت ہے کہ مختلف نظام کس طرح بات چیت کرتے ہیں۔

ورژن کنٹرول
سی آئی پائپ لائن
linting آلہ
ایک عمل بنائیں

یہ سمجھنا کہ یہ سسٹم کیسے مل کر کام کرتے ہیں آپ کو اندازہ لگانے کے بجائے منظم طریقے سے مسائل کو ڈیبگ کرنے کی اجازت دیتا ہے۔

اگلی بار جب آپ کی پل کی درخواست ناکام ہو جائے گی، تو آپ کو بالکل پتہ چل جائے گا کہ کہاں سے شروع کرنا ہے اور اسے کیسے ٹھیک کرنا ہے۔

CI کے مسائل کو ڈیبگ کرنا شروع میں بہت زیادہ ہو سکتا ہے، لیکن ایک منظم انداز آپ کو ناکامیوں کو بہتری کے واضح راستے میں تبدیل کرنے میں مدد کر سکتا ہے۔