بررسی راهنمای توسعه افزونه‌های گنوم

به بهانه‌ی اضافه شدن قانون جدیدی که افزونه‌های ساخته شده با هوش مصنوعی رو از ورود به لیست افزونه‌های گنوم منع میکنه، بیاید راهنمای توسعه‌ افزونه‌هارو به طور اجمالی بررسی کنیم. همه‌ی افزونه‌ها طبق این راهنما و قوانین از نظر امنیت، کد مخرب و تهدیدهای احتمالی بررسی میشن

اگر اولین بار هست که افزونه می‌نویسید، این پست احتمالا براتون ارزشمند خواهد بود.

بخش صفرم: اصول پایه‌ی چرخه‌ی حیات افزونه

هر افزونه باید از یه الگوی استاندارد پیروی کنه:

• قبل از اجرای ()enable نباید هیچ تغییری توی GNOME Shell ایجاد بشه.
• تمام ساختن اشیاء، اتصال سیگنال‌ها و اضافه کردن منابع به حلقه‌ی اصلی باید توی ()enable انجام بشه.
• هر چیزی که داخل ()enable ساخته شده، باید داخل ()disable به‌طور کامل پاک‌سازی بشه.

این قاعده مهم‌ترین معیار پذیرش افزونه‌ها تو فرایند بازبینی هست.

بخش اول: اشیاء ثابت و مدیریت حافظه

«منبع تصویر»

افزونه‌ها می‌تونند از نوع‌های داخلی جاوااسکریپت مثل موارد پایین در سطح ماژول استفاده کنن:

• Map
• Set
• RegExp
• آرایه‌ها و اشیاء ساده

اما:

• استفاده از کلاس‌های GObject مثل Gio.Settings یا St.Widget خارج از enable() ممنوعه.
• هر داده‌ی پویا که در زمان اجرا ذخیره میشه، باید تو disable() پاک شود (مثلاً با clear()).

هدف این قانون جلوگیری از نشتی حافظه و باقی‌ماندن داده‌ها پس از غیرفعال شدن افزونه‌ست.

بخش دوم: مدیریت اشیاء، ویجت‌ها و سیگنال‌ها

هر شیء یا ویجتی که در enable() ساخته میشه باید:

• در disable() نابود بشه.
• هیچ مرجعی بهش باقی نمونه.

همچنین:

• هر سیگنالی که با connect() متصل میشه، باید با disconnect() قطع بشه.
• شناسه‌ی هر اتصال باید ذخیره و در زمان غیرفعال شدنش آزاد بشه.

عدم رعایت این قوانین یکی از شایع‌ترین دلایل رد شدن افزونه‌هاست.

بخش سوم: منابع حلقه‌ی اصلی

اگه از تایمر یا منابع حلقه اصلی استفاده می‌کنید:

• تمام منابعی که با GLib.timeout_add() یا توابع مشابه ساخته میشن، باید توی disable() با GLib.Source.remove() حذف شوند.
• حتی اگه callback در آخر false برمیگردونه، باز هم حذف دستی الزامیه.

بخش چهارم: ماژول‌های منسوخ‌شده و ممنوع

استفاده از ماژول‌های قدیمی ممنوعه. جایگزین‌های مدرن باید استفاده بشن:

• به‌جای ByteArray از TextDecoder و TextEncoder استفاده کنید.
• به‌جای Lang از کلاس‌های ES6 و bind() استفاده بشه.
• به‌جای Mainloop از GLib.timeout_add() یا setTimeout() استفاده کنید.

بخش پنجم: جداسازی صحیح پردازش‌ها

گنوم افزونه‌هارو در دو محیط جدا اجرا می‌کنه:

در محیط Shell (extension.js)

استفاده از این کتابخانه‌ها ممنوعه:

• Gtk
• Gdk
• Adw

در محیط تنظیمات (prefs.js)

استفاده از این کتابخانه‌ها ممنوعه:

• Clutter
• Meta
• St
• Shell

این تفکیک برای جلوگیری از تداخل کتابخانه‌ها انجام میشه.

بخش ششم: عدم دخالت در سیستم افزونه‌ها

افزونه‌ها نباید:

• افزونه‌های دیگه رو تغییر بدن.
• اونارو فعال/غیرفعال یا reload کنن.
• به‌صورت مستقیم با سیستم مدیریت افزونه‌ها دستکاری انجام بدن.

بخشم هفتم: کیفیت کد و خوانایی

«منبع تصویر»

کد افزونه باید:

• قابل خوندن باشه
• ساختار منطقی داشته باشه
• بدون فشرده‌سازی یا مبهم‌سازی (obfuscation) ارائه بشه

بخش هشتم: لاگ‌نویسی (Logging)

افزونه نباید لاگ بیش‌ازحد تولید کنه.

لاگ‌ها فقط باید برای خطاهای مهم یا پیام‌های ضروری استفاده بشن. استفاده‌ی افراطی از console.log باعث رد شدن افزونه میشه.

بخش نهم: اسکریپت‌ها و باینری‌های خارجی

استفاده از فایل‌های خارجی به‌شدت محدود شده:

• قرار دادن فایل‌های باینری در افزونه ممنوعه.
• پردازش‌های خارجی باید به‌درستی خاتمه یابند.
• اسکریپت‌ها باید تا حد امکان با GJS نوشته بشن.
• اسکریپت‌ها باید دارای مجوز (License) معتبر باشن.

نصب ماژول‌های npm یا pip فقط با اقدام مستقیم کاربر مجاز هست (مثلاً دکمه‌ای در بخش تنظیمات).

بخش دهم: دسترسی به کلیپ‌بورد

اگر افزونه شما به کلیپ‌بورد دسترسی داره:

• باید این موضوع رو به‌وضوح توی توضیحات افزونه اعلام کنید.
• انتقال داده‌ی کلیپ‌بورد بدون تعامل کاربر ممنوع هست.
• نباید میانبر پیش‌فرض برای کار با کلیپ‌بورد تعریف بشه.

بخش یازدهم: الزامات عملکردی

افزونه باید:

• واقعاً کاربردی باشه
• عملکرد پایه‌ای داشته باشه
• تنظیماتش (در صورت وجود) کار کنه

افزونه‌های کاملاً بی‌استفاده یا شکسته رد میشن.

بخش دوازدهم سیاست مربوط به کد تولیدشده با AI

«منبع تصویر»

این بخش که تازه اضافه شده میگه که، استفاده از هوش مصنوعی به‌عنوان ابزار کمکی مشکلی نداره، اما:

• کد نباید شامل بخش‌های بی‌معنی یا غیرضروری باشه.
• از API های خیالی استفاده نشده باشه.
• کامنت‌ها شبیه پرامپت‌های LLM نباشن.
• توسعه‌دهنده باید بتونه کدشو توضیح بده.

بخش سیزدهم: استانداردهای فایل metadata.json

فایل metadata.json باید معتبر و دقیق باشه و اطلاعات واقعی افزونه رو منعکس کنه.

نکات مهم:

• uuid باید فرمت استاندارد داشته باشه
• shell-version فقط نسخه‌های پایدار و حداکثر یک نسخه‌ی درحال‌توسعه رو شامل بشه
• url باید به مخزن پروژه اشاره کنه

بخش چهاردهم: تله‌متری

افزونه‌ها نباید هیچ‌گونه سیستم تله‌متری یا ردیابی کاربر داشته باشن.

بخش پانزدهم: محدودیت‌های قانونی و محتوایی

افزونه‌ها باید:

• با «قوانین رفتار جامعه GNOME» سازگار باشن.
• محتوای سیاسی ترویج نکنن.
• محتوای دارای حق نشر یا علائم تجاری را بدون اجازه استفاده نکنن.
• تحت مجوزهای سازگار با GPL منتشر بشن.

بخش شانزدهم: توصیه‌های تکمیلی

• فایل‌های غیرضروری را در بسته افزونه قرار ندهید.
• از ESLint برای بررسی کیفیت کد استفاده کنید.
• رابط کاربری تنظیمات رو مطابق GNOME HIG طراحی کنید.

بخش هفدهم: منابع برای دریافت کمک

در صورت نیاز میتونید از این منابع کمک بگیرید:

• اتاق Matrix افزونه‌های GNOME
• انجمن discourse.gnome.org
• و همچنین، کانال گنوم فارسی در تلگرام :).