این سند نحوه ایجاد یک افزونه جدید را مورد بحث قرار می‌دهد. اگرچه فرآیندی که شرح می‌دهد برای ایجاد افزونه‌های شخص ثالث است، می‌توانید از آن به عنوان راهنمایی برای ایجاد افزونه‌های شخص ثالث استفاده کنید.
برای مشاهده‌ی افزونه‌ها، به بخش افزونه‌ها مراجعه کنید.
برای آشنایی سریع با نحوه‌ی ساخت افزونه، به گفتگوی «نحوه‌ی ساخت افزونه (۲۰۲۱)» ما مراجعه کنید.
شخص اول در مقابل شخص ثالث
کاربر هدف برای یک افزونه، توسعه‌دهنده‌ای است که افزونه را از طریق npm پیدا کرده و از آن استفاده می‌کند.
افزونه‌های شخص ثالث توسط تیم Blockly پشتیبانی می‌شوند و تحت دامنه @blockly در npm منتشر می‌شوند. آنها به گونه‌ای طراحی شده‌اند که در طیف گسترده‌ای از برنامه‌های Blockly قابل استفاده باشند و پایدار و استفاده از آنها آسان است. آنها در blockly-samples ذخیره می‌شوند. یک فیلد برای تنظیم سرعت موتور می‌تواند در بسیاری از پروژه‌های رباتیک مورد استفاده قرار گیرد و کاندیدای خوبی برای یک افزونه شخص ثالث است.
افزونه‌های شخص ثالث به طور مستقل نگهداری و منتشر می‌شوند. آنها ممکن است پیچیده‌تر، تجربی‌تر یا برای طیف محدودتری از برنامه‌های Blockly باشند. بهتر است فیلدی برای ویرایش یک شیء خاص که توسط طرحواره پایگاه داده شما تعریف شده است، به عنوان یک افزونه شخص ثالث باشد.
معیارهای شخص اول
افزونه‌های شخص ثالث باید این الزامات را داشته باشند:
- روی تمام پلتفرم‌های اصلی کار می‌کند، مگر اینکه تیم Blockly معافیتی به آن بدهد.
- کروم، فایرفاکس، سافاری، اج
- نویسنده‌ای داشته باشید که مایل باشد در سال اول اشکالات را برطرف کند.
- به طور مسدود میمون وصله نکنید.
- یک API (رابط برنامه‌نویسی کاربردی) واضح و مستند داشته باشید.
- توابع خصوصی یا پکیج را از هسته Blockly فراخوانی نکنید، مگر اینکه تیم Blockly به شما اجازه این کار را داده باشد.
- بازنویسی توابع پکیج روی زیرکلاسی که تعریف می‌کنید مجاز است.
- اگر معافیت می‌خواهید، در بخش blockly-samples از ما سوال کنید.
- آزمایش‌هایی داشته باشید.
فرآیند
افزونه‌ها چهار مرحله را طی می‌کنند: پیشنهاد ، بحث ، پیاده‌سازی و انتشار .
پیشنهاد
یک افزونه به عنوان یک پیشنهاد شروع می‌شود. شما می‌توانید با ایجاد یک مشکل جدید با الگوی درخواست ویژگی ، یک افزونه پیشنهاد دهید. برای اطلاعات بیشتر، در مورد نحوه نوشتن درخواست ویژگی مطالعه کنید.
علاوه بر اطلاعات اولیه درخواست ویژگی، یک پیشنهاد افزونه باید شامل موارد زیر باشد:
- API که افزونه نمایش می‌دهد.
- APIهایی که برای پشتیبانی از افزونه باید در هسته Blockly اضافه یا تغییر داده شوند.
- اسکرین‌شات‌ها، گیف‌ها یا ماکت‌ها، اگر افزونه شامل ویژگی‌های رابط کاربری باشد.
- توضیحی در مورد اینکه چرا باید یک افزونه شخص ثالث باشد نه یک افزونه شخص ثالث.
تیم Blockly پیشنهادات دریافتی را بررسی می‌کند و یا مشکل را حل می‌کند یا موافقت می‌کند که این یک افزونه‌ی خوب شخص ثالث باشد.
بحث
در مرحله بعد، یک افزونه وارد مرحله بحث می‌شود. این مرحله شامل موارد زیر است:
- شفاف‌سازی عملکرد مورد نظر.
- توضیح API افزونه.
- برنامه‌ریزی برای اجرا.
- برنامه ریزی برای آزمون ها.
- بحث در مورد تغییرات API در هسته Blockly.
- تقسیم افزونه‌های بزرگ به مراحل پیاده‌سازی
- نامگذاری افزونه، بر اساس قراردادهای نامگذاری ما.
- تأیید رعایت تمام معیارهای شخص اول .
این بحث معمولاً در مورد مشکل گیت‌هاب اتفاق می‌افتد. هرچه دامنه افزونه کوچک‌تر باشد، مرحله بحث سریع‌تر انجام می‌شود. افزونه‌های بزرگ‌تر ممکن است توجه جامعه و نظرات قوی در مورد راه‌حل درست را جلب کنند. اگر این اتفاق در مورد مشکل شما رخ می‌دهد، تبریک می‌گویم! شما چیزی پیدا کرده‌اید که مردم به آن اهمیت می‌دهند.
هدف این است که در پایان مرحله بحث، تمام تصمیمات اصلی طراحی گرفته شده باشد و فهرست روشنی از مراحل اجرا وجود داشته باشد. هر دو باید در نظرات مربوط به موضوع مستند شوند.
در طول بحث، ممکن است تصمیم بگیریم که یک افزونه باید یک افزونه شخص ثالث باشد و تحت دامنه @blockly منتشر نشود. در این صورت، دلیل آن را توضیح داده و موضوع را می‌بندم.
وقتی بحث تمام شد، یکی از اعضای تیم Blockly اعلام می‌کند که طرح آماده اجرا است.
پیاده‌سازی
مراحل پیاده‌سازی شامل موارد زیر است:
- اجرای
npx @blockly/create-packageبرای راه‌اندازی افزونه و دایرکتوری آن از یک الگو. اطلاعات بیشتر... - پیاده‌سازی منطق اصلی افزونه.
- پیاده‌سازی رابط کاربری (UI) در صورت نیاز
- تست افزونه، با استفاده از Mocha.
- مستندسازی افزونه، شامل
README.
اگر افزونه‌ای پیشنهادی برای پیاده‌سازی تأیید شده است و شما مایل به کار روی آن هستید، در مورد مشکل نظر دهید و بپرسید که آیا هنوز برای مشارکت باز است یا خیر.
پیاده‌سازی می‌تواند توسط چندین مشارکت‌کننده به صورت موازی انجام شود. شما می‌توانید یک افزونه را به صورت مشارکتی در انشعاب خود یا از طریق درخواست‌های pull در این مخزن پیاده‌سازی کنید. اگر می‌خواهید روی افزونه‌ای در این مخزن همکاری کنید، از تیم Blockly بخواهید که یک شاخه ویژگی برای شما ایجاد کند.
افزونه‌ها باید به فایل gh-pages/_index.html در شاخه master blockly-samples اضافه شوند. این کار باعث می‌شود که آنها در سایت افزونه‌های ما ظاهر شوند. افزونه‌های شخص ثالث باید به صفحه آزمایشی خود اشاره کنند. افزونه‌های شخص ثالث نیز می‌توانند به این صفحه اضافه شوند و می‌توانند به لینکی که مالک آنها انتخاب کرده است، مانند نسخه آزمایشی میزبانی شده یا صفحه npm، اشاره کنند.
انتشارات
در نهایت، انتشار . تیم Blockly از Lerna برای مدیریت نسخه‌بندی و انتشار همه افزونه‌ها استفاده می‌کند.
هر پنجشنبه، هر افزونه‌ای که از آخرین انتشارش تغییر کرده باشد، منتشر می‌شود. اگر نیاز دارید تغییری زودتر منتشر شود، لطفاً آن را در درخواست pull خود ذکر کنید.
سایت افزونه‌ها نیز هر زمان که افزونه‌ها منتشر شوند، به‌روزرسانی می‌شود.
افزونه‌هایی که آماده انتشار نیستند باید در package.json خود به private علامت‌گذاری شوند. این اتفاق ممکن است زمانی رخ دهد که یک افزونه به یک تغییر هنوز منتشر نشده در هسته Blockly متکی باشد. هسته Blockly در آخرین هفته هر سه ماه (هر سه ماه یک بار) منتشر می‌شود.