یک افزونه اضافه کنید

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

برای مروری بر افزونه ها، به پلاگین ها مراجعه کنید.

برای معرفی سریع ایجاد یک پلاگین، به بحث ما در مورد نحوه ساخت یک پلاگین (2021) مراجعه کنید.

شخص اول در مقابل شخص ثالث

کاربر هدف پلاگین توسعه دهنده ای است که افزونه را از طریق npm پیدا کرده و از آن استفاده می کند.

پلاگین های شخص اول توسط تیم Blockly پشتیبانی می شوند و تحت دامنه @blockly در npm منتشر می شوند. آنها به گونه ای طراحی شده اند که در طیف گسترده ای از برنامه های Blockly قابل استفاده باشند و پایدار و آسان برای استفاده هستند. آنها در نمونه های بلوکی ذخیره می شوند. زمینه ای برای تنظیم سرعت موتور می تواند در بسیاری از پروژه های رباتیک استفاده شود و کاندیدای خوبی برای یک پلاگین شخص اول است.

افزونه های شخص ثالث به طور مستقل نگهداری و منتشر می شوند. آنها ممکن است پیچیده‌تر، آزمایشی‌تر یا برای محدوده محدودتری از برنامه‌های Blockly باشند. یک فیلد برای ویرایش یک شی خاص که توسط طرح پایگاه داده شما تعریف شده است به عنوان یک افزونه شخص ثالث بهتر است.

معیارهای طرف اول

افزونه های شخص اول باید این شرایط را داشته باشند:

• روی همه پلتفرم‌های اصلی کار کنید، مگر اینکه توسط تیم Blockly معافیت داده شود.
  • کروم، فایرفاکس، سافاری، اج
• نویسنده ای داشته باشید که مایل به رسیدگی به اشکالات در سال اول باشد.
• Blockly را میمون پچ نکنید.
• یک API به وضوح تعریف شده و مستند داشته باشید.
• توابع خصوصی یا بسته را از هسته Blockly فراخوانی نکنید، مگر اینکه توسط تیم Blockly معافیت داده شود.
  • نادیده گرفتن توابع بسته در زیر کلاسی که شما تعریف می کنید مجاز است.
  • اگر معافیت می‌خواهید، در شماره‌ای در مورد نمونه‌های بلوکی از ما بپرسید.
• تست داشته باشید

روند

پلاگین ها چهار مرحله را طی می کنند: پیشنهاد ، بحث ، اجرا و انتشار .

پیشنهاد

یک افزونه به عنوان یک پیشنهاد شروع می شود. می توانید با ایجاد یک شماره جدید در قالب درخواست ویژگی، یک افزونه پیشنهاد دهید.

نحوه نوشتن درخواست ویژگی را بخوانید

علاوه بر اطلاعات اولیه درخواست ویژگی، یک پیشنهاد افزونه باید شامل موارد زیر باشد:

• API که افزونه در معرض نمایش قرار می دهد.
• API هایی که برای پشتیبانی از افزونه باید در core Blockly اضافه یا تغییر داده شوند.
• اگر افزونه دارای ویژگی‌های رابط کاربری باشد، اسکرین‌شات، گیف یا ماکت‌ها.
• توضیحی در مورد اینکه چرا باید یک پلاگین شخص اول باشد تا یک افزونه شخص ثالث.

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

بحث

بعد، یک پلاگین وارد مرحله بحث می شود. این مرحله شامل:

• شفاف سازی عملکرد مورد نظر.
• شفاف سازی API افزونه.
• برنامه ریزی برای اجرا.
• برنامه ریزی برای آزمون ها
• بحث در مورد تغییرات API در هسته Blockly.
• شکستن پلاگین های بزرگ به مراحل پیاده سازی
• نامگذاری افزونه، بر اساس قراردادهای نامگذاری ما.
• تایید تمام معیارهای شخص اول برآورده خواهد شد.

این بحث به طور کلی در مورد موضوع GitHub اتفاق می افتد. هرچه دامنه پلاگین کمتر باشد، مرحله بحث سریعتر می شود. افزونه های بزرگتر ممکن است توجه جامعه و نظرات قوی را در مورد راه حل مناسب جلب کند. اگر در مورد مشکل شما این اتفاق می افتد، تبریک می گویم! شما چیزی را پیدا کرده اید که مردم به آن اهمیت می دهند.

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

در طول بحث ممکن است تصمیم بگیریم که یک افزونه باید یک افزونه شخص ثالث باشد و تحت محدوده @blockly منتشر نشود. در آن صورت دلیل آن را توضیح می دهیم و موضوع را می بندیم.

وقتی بحث کامل شد، یکی از اعضای تیم Blockly یادداشت می‌کند که برای اجرا آماده است.

پیاده سازی

مراحل پیاده سازی شامل:

• اجرای npx @blockly/create-package برای راه اندازی افزونه و دایرکتوری آن از طریق یک الگو. بیشتر بدانید...
• پیاده سازی منطق اصلی برای افزونه.
• پیاده سازی UI، در صورت نیاز.
• تست پلاگین با استفاده از موکا.
• مستندسازی افزونه، از جمله README .

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

پیاده سازی ممکن است توسط چندین مشارکت کننده به طور موازی انجام شود. می‌توانید یک پلاگین را به‌صورت مشترک در فورک خود یا از طریق درخواست‌های کشش در مقابل این مخزن پیاده‌سازی کنید. اگر می‌خواهید روی افزونه‌ای در این مخزن همکاری کنید، از تیم Blockly بخواهید که یک شاخه ویژگی برای شما ایجاد کند.

افزونه ها باید به فایل gh-pages/index.md در شاخه master blockly-samples اضافه شوند. این باعث می شود که آنها در سایت افزونه های ما ظاهر شوند. افزونه های شخص اول باید به صفحه آزمایشی خود اشاره کنند. افزونه‌های شخص ثالث نیز می‌توانند به این صفحه اضافه شوند و می‌توانند به پیوندی که مالک آنها انتخاب می‌کند، مانند یک نسخه نمایشی میزبانی شده یا صفحه npm اشاره کنند.

انتشار

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

هر پنجشنبه هر پلاگینی که از آخرین نسخه خود تغییر کرده است منتشر می شود. اگر نیاز دارید که تغییری زودتر منتشر شود، لطفاً آن را در درخواست pull خود یادداشت کنید.

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

افزونه هایی که برای انتشار آماده نیستند باید در package.json خود private گذاری شوند. این ممکن است در صورتی اتفاق بیفتد که یک افزونه به تغییری که هنوز منتشر نشده در هسته Blockly متکی باشد. Core Blockly در هفته آخر هر سه ماهه (هر سه ماه یک بار) منتشر می شود.