مین مواد پر جائیں

آرکیٹیکچر فیصلہ ریکارڈز (ADRs)

🎯 فیصلوں کو دستاویز کرنے کی وجہ؟​

آرکیٹیکچر فیصلہ ریکارڈز کتاب کی ترقی کے دوران کئے گئے اہم انتخابات کو قید کرتے ہیں، جن میں شامل ہیں:

  • سیاق و سباق: ہمیں فیصلہ کیوں کرنا پڑا
  • فیصلہ: ہم نے کیا انتخاب کیا
  • متبادل: ہم نے کیا اور غور کیا
  • دلیل: اس انتخاب نے کیوں جیت حاصل کی
  • نتائج: سود و زیاں اور اثرات

ADRs فراہم کرتے ہیں:

  • ✅ شفافیت: کیوں سمجھنا، صرف کیا نہیں
  • ✅ آن بورڈنگ: نئے شراکت دار استدلال سیکھتے ہیں
  • ✅ مستقل مزاجی: مستقبل کے فیصلے ماضی کے نمونوں کا حوالہ دیتے ہیں
  • ✅ جوابدہی: فیصلوں کو جائزہ لیا جا سکتا ہے اور ترمیم کی جا سکتی ہے

📋 تمام ADRs​

ADR-001: Docusaurus برائے کتاب کی ترسیل​

حالت: ✅ قبول شدہ | تاریخ: 2025-11-29

فیصلہ: Docusaurus (v3.x کے ساتھ TypeScript) کو کتاب کے پلیٹ فارم کے طور پر استعمال کریں

سیاق و سباق:

  • ہیکاتھون کو GitHub Pages پر کتاب کو ڈپلائے کرنے کی ضرورت ہے
  • دوہرے سائیڈ بارز کی ضرورت ہے (کتاب کے ابواب + طریقہ کار کی نمائش)
  • ROS 2 کوڈ کی مثالوں کی حمایت کرنا ضروری ہے (Python, C++, YAML, Bash, XML)
  • طلباء کو پیشہ ورانہ، موبائل-رسپانسو تجربہ کی ضرورت ہے

متبادل غور کیا گیا:

  1. GitBook - مسترد (ملکیتی، GitHub Pages نہیں)
  2. MkDocs + Material - مسترد (محدود سائیڈ بار لچک)
  3. mdBook - مسترد (کثیر سائیڈ بار کی حمایت نہیں)
  4. VuePress - مسترد (Docusaurus کے مقابلے میں چھوٹی کمیونٹی)
  5. Jupyter Book - مسترد (مارک ڈاؤن-پہلے مواد کے لئے زیادہ)

دلیل:

  • GitHub Pages ڈپلائمنٹ پہلی درجہ کی ہے (سرکاری گائیڈ)
  • دوہرے سائیڈ بارز کتاب + طریقہ کار کی نمائش کی حمایت کرتے ہیں
  • React ایکوسسٹم مستقبل کے تعاملی اجزاء کو ممکن بناتا ہے
  • 50k+ GitHub ستارے، فعال ترقی
  • پورے ROS 2 اسٹیک کے لئے سنٹیکس ہائی لائٹنگ
  • Mermaid ڈایاگرام کی حمایت بلٹ-ان ہے

نتائج:

  • ✅ پیشہ ورانہ، رسپانسو سائٹ کے ساتھ تلاش
  • ✅ شراکت داروں کے لئے ابواب کا اضافہ کرنا آسان (مارک ڈاؤن)
  • ✅ GitHub Actions کے ذریعے خودکار ڈپلائمنٹ
  • ⚠️ Node.js کی ضرورت (مقامی تعمیرات کے لئے npm کی ضرورت ہے)
  • ⚠️ اعلی درجہ کی حسب ضرورت کے لئے React کا علم مفید ہے

→ Read Full ADR-001

ADR-002: GitHub Pages ڈپلائمنٹ حکمت عملی​

حالت: ⚠️ ADR-006 کے ذریعے متروک | تاریخ: 2025-11-29

فیصلہ: GitHub Actions کا استعمال کرتے ہوئے GitHub Pages پر خودکار ڈپلائمنٹ کے لئے actions/deploy-pages@v4

سیاق و سباق:

  • Docusaurus (ADR-001) کا انتخاب کرنے کے بعد، ڈپلائمنٹ حکمت عملی کی ضرورت ہے
  • ہیکاتھون نے صراحت کی ہے کہ GitHub Pages کی ضرورت ہے
  • خودکار (کوئی دستی npm run deploy کمانڈز نہیں)
  • مفت درجہ کی ضرورت ہے (تعلیمی/ہیکاتھون سیاق و سباق)

متبادل غور کیا گیا:

  1. Netlify - مسترد (GitHub Pages نہیں، ہیکاتھون کی ضرورت)
  2. Vercel - مسترد (GitHub Pages نہیں)
  3. دستی gh-pages شاخ - مسترد (کوئی خودکاری نہیں، غلطی کا خطرہ)
  4. خود میزبانی (AWS S3 + CloudFront) - مسترد (لاگت، پیچیدگی)
  5. Read the Docs - مسترد (GitHub Pages نہیں، Sphinx مرکوز)

ڈپلائمنٹ بہاؤ:

Push to main → GitHub Actions → Build → Deploy → Live Site
     (2-4 minutes total)

دلیل:

  • GitHub اور Docusaurus کی طرف سے سرکاری حل کی سفارش کی گئی
  • دھکیلنے سے ڈپلائمنٹ خودکاری (کوئی دستی مداخلت نہیں)
  • راستہ فلٹرنگ GitHub Actions منٹ بچاتا ہے
  • دستی ٹرگر کی صلاحیت (workflow_dispatch)
  • ڈیبگنگ کے لئے تعمیر کی مصنوعات محفوظ رکھی گئیں
  • عوامی ریپوزٹریز کے لئے مکمل طور پر مفت

نتائج:

  • ✅ 3-5 منٹ میں دھکیلنے سے ڈپلائمنٹ
  • ✅ تعمیر کی ناکامیاں بری ڈپلائمنٹس کو روکتی ہیں
  • ✅ طلباء اپنے ورژنز کو فورک اور ڈپلائے کر سکتے ہیں
  • ⚠️ کوئی PR پیش نظارہ ڈپلائمنٹس نہیں (اس کے لئے Netlify کی ضرورت ہوگی)
  • ⚠️ GitHub Pages 1GB سائٹ کی حد (تک پہنچنے کا امکان کم ہے)

→ Read Full ADR-002

ADR-003: ROS 2 Humble بطور اولین تقسیم​

حالت: ✅ قبول شدہ | تاریخ: 2025-11-29

فیصلہ: تمام کتاب کے مواد کے لئے ROS 2 Humble Hawksbill کو اولین اور ضروری تقسیم کے طور پر استعمال کریں

سیاق و سباق:

  • کتاب کو 2025-2027 تعلیمی سالوں کے دوران حمایت یافتہ ROS 2 تقسیم کا انتخاب کرنا ہوگا
  • طویل مدتی استحکام، وسیع ہارڈویئر حمایت، مضبوط ایکوسسٹم کی ضرورت ہے
  • صنعتی تعیناتیوں کے ساتھ ہم آہنگ ہونا ضروری ہے

متبادل غور کیا گیا:

  1. ROS 2 Iron - مسترد (EOL نومبر 2024، پہلے ہی متروک)
  2. ROS 2 Jazzy - مسترد (تصنیف کے دوران جاری نہیں، نابالغ ایکوسسٹم)
  3. ROS 1 Noetic - مسترد (EOL مئی 2025، میراثی پلیٹ فارم)
  4. ملٹی-تقسیم حمایت - مسترد (2x دیکھ بھال کا بوجھ)

دلیل:

  • Humble LTS مئی 2027 تک حمایت (کتاب کے استعمال کے ساتھ مکمل اوورلیپ)
  • Jetson JetPack 5.x Ubuntu 22.04 پر Humble کو مکمل طور پر حمایت کرتا ہے
  • MoveIt 2، Nav2، ros2_control سب Humble پر مستحکم ہیں
  • صنعتی معیار (Boston Dynamics، Figure AI Humble استعمال کرتے ہیں)

نتائج:

  • ✅ 2027 تک کوڈ کی مثالیں بغیر تبدیلی کے کام کرتی ہیں
  • ✅ تمام ہارڈویئر درجات Humble کو بنیادی طور پر حمایت کرتے ہیں
  • ✅ 1000+ پیکجز apt کے ذریعے دستیاب ہیں
  • ⚠️ Iron/Jazzy سے نئی خصوصیات دستیاب نہیں ہیں

→ Read Full ADR-003

ADR-004: ملٹی-سمولیشن پلیٹ فارم حکمت عملی​

حالت: ✅ قبول شدہ | تاریخ: 2025-11-29

فیصلہ: Gazebo Classic، NVIDIA Isaac Sim، اور Unity (اختیاری) کے ساتھ ملٹی-سمولیشن حکمت عملی اپنائیں

سیاق و سباق:

  • فزیکل اے آئی کو مہنگے روبوٹس پر ڈپلائے کرنے سے پہلے سمولیشن کی ضرورت ہوتی ہے
  • مختلف ابواب کو مختلف سمولیشن صلاحیتوں کی ضرورت ہے (فزکس بمقابلہ فوٹوریلزم)
  • طلباء کے پاس مختلف ہارڈویئر ہوتے ہیں (صرف کلاؤڈ، Jetson، گیمنگ پی سی)

متبادل غور کیا گیا:

  1. صرف Gazebo - مسترد (وژن AI کے لئے ناکافی فوٹوریلزم)
  2. صرف Isaac Sim - مسترد (ہارڈویئر رکاوٹ، بنیادوں کے لئے زیادہ)
  3. صرف Unity - مسترد (ROS 2 انضمام بے ڈھنگا)
  4. PyBullet/MuJoCo - مسترد (کوئی سینسر سم