شراکت

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

بنیادی اصول

یہ کتاب سخت ہاؤس اسٹائل کی پیروی کرتی ہے۔ خلاصہ:

• طویل ڈیش نہیں۔ کوما، کولن، قوسین، یا دو جملے استعمال کریں۔
• گھسے پٹے جملے نہیں (“not only … but also”، “load-bearing”، اور ان جیسے)۔
• گرمجوش، سادہ، براہِ راست نثر۔ قاری سے براہِ راست مخاطب ہوں۔ مختصر جملے۔
• اصطلاحات کی پہلی بار استعمال پر تعریف کریں۔ کلیدی تصورات کو پہلی بار ذکر پر وکیپیڈیا سے جوڑیں۔
• صرف حقیقی حوالہ جات۔
• میٹرکس کے خاندان کا ہر موضوع ہیرا پھیری کی راہ اور حفاظتی حد کا نام لیتا ہے۔

مکمل اصول ریپوزٹری کی جڑ میں spec/conventions.md میں ہیں، اور مختصر ورژن اسلوب کے اصول ہے۔ ٹیسٹ میکانکی حصہ نافذ کرتے ہیں۔

تیاری

آپ کو Python 3 اور just چاہییں۔ یہ ریپوزٹری کتاب کا مواد اور تفصیل رکھتی ہے، ساتھ SvelteKit سائٹ (software-engineering-metrics.github.io/) جو اسے شائع شدہ ویب سائٹ میں رینڈر کرتی ہے۔

just         # list tasks
just test    # run the validation suite
just nav     # regenerate the generated navigation files
just stats   # topic and word counts

تبدیلی کرنا

1. متعلقہ رہنما پڑھیں: موضوعات کے لیے تصنیف، تیار کردہ فائلوں کے لیے نیویگیشن، ٹیسٹوں کے لیے ٹیسٹنگ۔
2. وہ سب سے چھوٹی تبدیلی کریں جو کام پورا کرے۔
3. اگر آپ موضوع شامل کرتے، ہٹاتے، نام بدلتے، یا دوبارہ نمبر دیتے ہیں تو ریپوزٹری کی جڑ میں spec/structure.md اپ ڈیٹ کریں اور just nav چلائیں۔
4. just test چلائیں۔ اسے پاس ہونا چاہیے۔
5. تبدیلیوں کے لاگ میں Unreleased کے تحت ایک سطر کا اندراج شامل کریں۔

کس پر کام کریں

• غلطیاں، غیر واضح حصے، یا پرانے حوالہ جات درست کریں۔
• مثالیں بہتر بنائیں، خاص طور پر ٹھوس کاروباری اور سرکاری مثالیں۔
• اقتباسات کو حقیقی ماخذ کے مقابل جانچیں۔
• ٹیمپلیٹ توڑے بغیر موضوع کے احاطے کی خالی جگہیں بھریں۔

کس سے بچیں

• تیار کردہ فائلیں (README.md، ہر لوکیل کی index.md، front-matter/table-of-contents.md، اور topics/09-07-index.md) ہاتھ سے ایڈٹ نہ کریں۔ اس کے بجائے موضوعات بدلیں اور just nav چلائیں۔
• en-001، en-gb، یا en-us کو براہِ راست ایڈٹ نہ کریں؛ وہ tools/localize.py کے ذریعے en-gb-oxendict سے اخذ ہوتے ہیں۔
• spec/structure.md اپ ڈیٹ کیے بغیر موضوع شامل نہ کریں۔
• طویل ڈیش یا ممنوعہ جملے شامل نہ کریں؛ ٹیسٹ ناکام ہوں گے۔

مسائل کی اطلاع

ایک ایسا issue کھولیں جو مسئلے، فائل اور موضوع، اور جہاں متعلقہ ہو درست ماخذ یا حوالے کو بیان کرے۔ چھوٹی، مخصوص اطلاعات پر عمل کرنا سب سے آسان ہے۔