پروژه جهانی موجا

این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.

خلاصه ی پروژه

سازمان منبع باز:

موجا جهانی

نویسنده فنی:

تلازیپاندا

نام پروژه:

مستندات راهنمای حضور فنی برای FLINT

طول پروژه:

طول استاندارد (3 ماه)

شرح پروژه

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

مسائل پروژه

در زیر فهرستی از مهم‌ترین مسائل مربوط به مستندات کنونی آمده است: - دستورالعمل‌های راهنمای راه‌اندازی محلی بهم ریخته و در نتیجه شروع کار برای یک مشارکت‌کننده جدید دشوار می‌شود. - مخازن چندگانه FLINT فاقد مستندات مربوط به هدف خود هستند و به یکدیگر مرتبط نیستند و شناسایی مخزن مورد نظر برای تازه وارد را دشوار می کند. - نصب ویندوز به خوبی مستند شده است اما اسناد نصب مبتنی بر لینوکس جای بهبود دارد. - گردش کار Git در حال حاضر بخشی از مستندات نیست

راه حل پیشنهادی

این پیشنهاد راه حلی را برای هدایت مشارکت کنندگان جدید از طریق نصب فنی ارائه می دهد تا مشارکت کنندگان جدید بتوانند به راحتی با حداقل پشتیبانی از سوی نگهبانان شروع به کار کنند. این را می‌توان با بازسازی اسناد فعلی به‌منظور تبدیل آن برای مبتدیان و همچنین حفظ یک مخزن مستقل مرکزی برای تمام اسناد موجود به دست آورد. این پروژه به سه مرحله تقسیم می‌شود: - - بررسی اسناد موجود و بازسازی: هدف از این مرحله بررسی راهنمای فعلی و اصلاح آن به‌گونه‌ای است که آن را مختصر و به راحتی برای مشارکت‌کنندگان جدید قابل درک کند. اسناد همچنین باید اصلاح شوند تا با افزودن نشان‌ها، شکلک‌ها و اطلاعات مربوط به مسائلی که با برچسب‌های فقط برای اولین بار یا برچسب‌های شماره اول خوب برچسب‌گذاری شده‌اند، آن را برای مبتدیان دوست‌دارتر کند. - ایجاد یک مخزن اسناد مستقل مرکزی: هدف این مرحله پیوند دادن تمام اسناد موجود به ترتیب منطقی در یک مخزن مستقل است. این شامل سفارش دستورالعمل های مشارکت، دستورالعمل های راه اندازی پروژه و راهنماهای گام به گام است. - اضافه کردن گردش کار Developer و وب سایت انجمن برای توسعه دهندگان جدید: هدف این مرحله اضافه کردن گردش کار Developer است که حاوی دستورالعمل های مشارکت git و معماری فنی پروژه به همراه دستورالعمل های تست و QA است. وب‌سایت انجمن پیشنهادی یک برنامه کاربردی تک صفحه‌ای خواهد بود که جریان کار، مسائل مربوط به اولین بار که می‌تواند توسط مشارکت‌کنندگان جدید ادعا شود و فهرستی از همه مشارکت‌کنندگان را نمایش می‌دهد. مرحله 1: بررسی اسناد موجود و بازسازی:

اسناد فعلی مخازن زیر را اصلاح کنید: - FLINT: مستندات فعلی خیلی مفصل نیستند و ترتیب متوالی کتابخانه های پیش نیاز مورد نیاز را ارائه نمی دهند. راهنماهای دستورالعمل گام به گام به pdf های مختلف تقسیم می شوند، اما می توانند در یک مکان واحد به شیوه ای مختصر تر یکپارچه شوند. همچنین، راهنمای نصب به ویندوز ارائه می شود، اما برای نصب لینوکس، هدایت مجدد به مخزن FLINT.docker ممکن است مفید باشد. - FLINT.docker: مستندات فعلی هدف از تنظیم این مخزن را که ارائه نصب لینوکس FLINT از طریق docker است، ارائه نمی کند. پشتیبانی از طریق docker فقط به اوبونتو 18.04 (Bionic Beaver) محدود می شود اما می تواند به سایر توزیع های مبتنی بر لینوکس نیز گسترش یابد. مستندات کنونی همچنین نیاز به تاکید بر روش متوالی راه اندازی dockerfiles و همچنین اطلاعات کافی در مورد نحوه ساخت از makefile دارد. - FLINT.example: مستندات فعلی هدف از تنظیم این مخزن که ارائه مثالی از نحوه استفاده از FLINT است را ارائه نمی دهد. اجرای نمونه های مختلف را می توان با دستورالعمل های خاص برای اجرا بهتر تفکیک کرد. ما همچنین باید این مخزن را به مخزن اصلی FLINT خود پیوند دهیم تا به کاربران راهی برای پیمایش در اینجا ارائه دهیم تا نمونه را در عمل بررسی کنند.

اطلاعات زیر باید به مستندات فعلی اضافه شود: - استفاده از Git و GitHub: این شامل دستورالعمل های گام به گام در مورد نحوه فورک کردن، کلون کردن و سپس تنظیم کنترل از راه دور برای مخزن است. همچنین اطلاعاتی در مورد نحوه تغییر پایه در برابر جدیدترین اصلی و مدیریت تضادهای ادغام ارائه می دهد. - نشان‌ها و شکلک‌ها: مستندات فعلی فاقد نشان‌ها و شکلک‌ها هستند که می‌تواند به مشارکت‌کنندگان جدید کمک کند تا احساس استقبال کنند و مشکلات را کمتر دلهره‌آور ببینند. - اطلاعات در مورد اولین تایمر/مسائل دوستانه مبتدی: این به هدایت مشارکت کنندگان جدید به مسائل مبتدی پسند و وب سایت انجمن کمک می کند. - اطلاعات مربوط به مخزن Import-me: مخزن Import-me به عنوان یک الگوی پایه برای شروع سریع هر مخزن Moja Global عمل می کند. در اسناد فعلی اهمیت آن ذکر نشده است. برای ذکر مخزن Import-me باید به روز شود و مراحل انتخاب آن به عنوان الگوی ایجاد یک مخزن جدید نیز باید اضافه شود. همچنین باید یک فرآیند مشخص برای کدنویس ها وجود داشته باشد تا ویژگی های اضافی را برای مخزن Import-me پیشنهاد دهند.

فاز 2: ایجاد یک مخزن اسناد مستقل مرکزی:

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

ابزار پیشنهادی برای این پلتفرم میزبانی Read The Docs به دلایل زیر است: - - رتبه بالایی در بین پلتفرم های میزبانی مختلف دارد. - به روز رسانی خودکار در commit فشار - راه اندازی آسان و پشتیبانی عیب یابی به راحتی به دلیل استفاده از جامعه بزرگ در دسترس است - اسناد با استفاده از reStructuredText فرمت شده و خروجی توسط Sphinx کامپایل می شود.

همه مطالب را به روشی منطقی ترتیب دهید:

ترتیب پیشنهادی محتوا به شرح زیر است: - - مقدمه ای بر مستندات توسعه دهنده: این بخش مقدمه ای بر Moja Global و FLINT را پوشش می دهد. - مشارکت: این بخش شامل بخش‌های فرعی «راه‌های مشارکت» (از نظر کد/گزارش اشکال/ترجمه/اسناد/سازمان‌دهی رویدادها و غیره) و «آیین رفتار» خواهد بود. - راه اندازی توسعه: این بخش شامل بخش های فرعی "Git & GitHub Workflow"، "Windows Installation"، "Linux Installation" است. - گردش کار توسعه دهنده: این بخش شامل بحث در مورد ابزارهای یکپارچه برای آزمایش و نحوه انجام آزمایش دستی در مورد درخواست کشش شما و موارد دیگر است که در فاز بعدی مستند شده است. - به ما بپیوندید: این بخش انجمن های اجتماعی مختلف مانند کانال های Slack را برای ارتباط و کار با Moja Global ارائه می دهد.

فاز 3: گردش کار توسعه‌دهنده و وب‌سایت انجمن را برای مشارکت‌کنندگان جدید اضافه کنید:

مستندات گردش کار توسعه دهنده:

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

• Tech Stack/Architecture مورد استفاده و ماژول های مختلف در کد: مستنداتی برای آشنایی مشارکت کنندگان جدید با پشته فناوری پیاده سازی شده، کتابخانه ها و ماژول های مختلف پایگاه کد.
• ابزارهای تست و پوشش یکپارچه: معرفی مشارکت‌کنندگان جدید به ابزارهای خط لوله CI/CD که برای آزمایش استفاده می‌شوند، ربات‌های پوشش و بررسی‌های خودکار کیفیت بر خلاف کد آنها اجرا می‌شوند. همچنین به آنها دستورالعمل هایی ارائه دهید که در صورت شکست آزمایش ها به چه کسی مراجعه کنند.
• ربات‌هایی که برای تسهیل روند کار استفاده می‌شوند، به عنوان مثال - Zulipbot: طراحی قالب‌های محتوا برای نمایش ربات‌ها و در دسترس بودن مستندات برای اینکه کاربران بتوانند ربات‌ها را درک کنند و حتی با مشارکت، پیکربندی ربات را بهبود ببخشند.
• آزمایش دستی و ارسال درخواست کشش: مستنداتی که باید در مورد نحوه آزمایش دستی درخواست‌های کشش در برابر استانداردهای خاص و نتایج آپلود از نظر اسکرین‌شات‌ها/گیف‌ها در ارسال درخواست‌های کشش ارائه شود.
• دستورالعمل‌های بازبینی درخواست کششی که باید توسط مشارکت‌کنندگان دنبال شود: دستورالعمل‌هایی در مورد برچسب‌گذاری تیم‌های خاص برای بازبینی و افزودن برچسب‌هایی مانند «نیاز به بررسی» به درخواست کشش برای اجازه دادن به نگهدارنده‌ها برای پاسخگویی.

وب سایت انجمن:

وب سایت انجمن دارای ویژگی های زیر خواهد بود:

• اطلاعات در مورد گردش کار ما: گردش کار شامل مجموعه اقداماتی است که یک مشارکت‌کننده جدید می‌تواند با آنها شروع کند، به عنوان مثال - ادعای اولین مشکل تایمر، و سپس ایجاد اولین مشکل تایمر برای شخص دیگری و کمک به دیگران با ارائه بازخورد و بررسی درخواست‌های کشش آنها.
• فهرست مشکلات فقط برای اولین بار: فهرستی از مسائلی که به طور خاص برای اولین بار یا مشارکت کنندگان جدید در نظر گرفته شده است.
• فهرست مسائل قدیمی: فهرستی از مسائلی که برای مدت طولانی روی آنها کار نشده است و از این رو برای انتخاب توسط مشارکت کنندگان در دسترس است.
• فهرست مشارکت‌کنندگان: فهرست مشارکت‌کنندگانی که تاکنون در مخازن Moja Global مشارکت داشته‌اند.
• مشارکت کنندگان اخیر: فهرست مشارکت کنندگانی که اخیراً در مخازن جهانی Moja همکاری کرده اند.
• پیوندهایی برای پیوستن به انجمن های گفتگو: اطلاعات و پیوندهایی برای پیوستن به انجمن Slack برای حل سؤالات آنها و بحث های بیشتر در مورد پروژه ها.