برنامه‌نویسی / مشارکت کنید

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

• صفحه اصلی ویکی
• برنامه‌نویسی
• طراحی
• تضمین کیفیت
• رویدادها
• مستندسازی
• وب‌گاه
• بومی‌سازی
• دسترسی‌پذیری
• بازاریابی
• گوناگونی
• راهنمای ویکی

• مرور کلی
• گزارش اشکالات
• کامپایل نرم‌افزار
• مروری کلی کد
• دستورات گیت
• اشکال‌زدایی
• هک‌های آسان
• برنامه انتشار
• پرسش‌های مکرر
• برنامه‌نویسان
• افزونه‌ها
• → اشکالات حل نشده

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

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

در این صفحه ما بر برنامه‌نویسان تمرکز داریم. ما برای همکاری با همه سطوح برنامه‌نویسان گشوده هستیم. لیبره آفیس یکی از بزرگ‌ترین، قدیمی‌ترین و اکنون شناخته شده‌ترین (پیش از این به عنوان اپن آفیس) بسته‌های نرم‌افزار آزاد است. اگر دانشجو هستید یا به دنبال کار برنامه‌نویسی هستید ، نوشتن «من برای لیبره آفیس کار کرده‌ام» یک امتیاز عالی در رزومه شما است. برنامه‌نویسان به بهبود پایه کد لیبره آفیس کمک می کنند. در ابتدا، حجم عظیم کد ممکن است ترسناک باشد، اما مستندات در حال بهبود هستند و از تیم برنامه‌نویسان موجود کمک دریافت خواهید کرد. این صفحه به شما کمک می‌کند تا اولین تغییرات خود را ارسال کنید. برای کمک گرفتن برای رسیدن به یک نمای کلی:

• نمای کلی کد گرافیکی
• مستندات مربوط به ماژول‌های مشخص
• چگونه یک ویجت سفارشی ایجاد کنیم؟
• DrawingLayer: چه چیزی باید در مورد آن بدانید؟
• پرسش‌های متداول

راهنمای گام به گام برای برنامه‌نویسان جدید

غرق در اندازه و پیچیدگی LibreOffice آسان است. منبع به زبان‌ها و قالب‌های مختلف نوشته شده است — C, C++, Java, Bash, JavaScript, Python, Perl, SQL, XML —و شامل تقریباً 102000 فایل (به استثنای تمام ترجمه‌ها) با 36000000 خط متن (7000000 خط کد منبع) است.

هیچ کس کل کد را با جزئیات درک نمی‌کند، اما ما برنامه‌نویسان اصلی زیادی داریم که هر کدام بخشی از کد را با جزئیات می‌دانند. این راهنمای گام به گام راه آسانی را نشان می‌دهد که از «خواستن مشارکت» تا ادغام موفقیت‌آمیز اولین وصله در شاخه اصلی (master) کد نرم‌افزار را نشان می‌دهد.

به کانال‌های ارتباطی ما وصل شوید

فهرست پستی ما libreoffice@lists.freedesktop.org است. توصیه می‌کنیم شما در آن مشترک شوید. همچنین می‌توانید فهرست پستی را به صورت برخط دنبال کنید.

برای گفتگوی برخط، از IRC در شبکه چت لیبرا #libreoffice-dev ^IRC:// استفاده می‌کنیم.

ساخت لیبره آفیس از کد منبع

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

ویندوز

برنامه‌نویسان ویندوز نیاز به نصب Cygwin و سایر ابزارهای کمکی دارند. ساده‌ترین راه استفاده از LibreOffice Development Environment (LODE) است. دستورالعمل‌های دقیق کامپایل روی ویندوز نیز موجود است.

مک او اس

پیشنهاد می‌کنیم دستورالعمل‌هایی را دنبال کنید که از محیط توسعه LibreOffice (LODE) استفاده می‌کنند. اطلاعات و جزئیات بیشتر در مورد Xcode را می توانید در مقاله Building LibreOffice در macOS بخوانید.

لینوکس

لینوکس (بیشتر توزیع‌ها) را می‌توان با استفاده از نصب کننده‌های بسته راه‌اندازی کرد. پیشنهاد می کنیم کامپایل روی لینوکس را دنبال کنید

برای ارسال تغییرات آماده شوید

پس از کامپایل موفقیت‌آمیز لیبره آفیس، آماده ارسال تغییرات هستید. ما از gerrit برای پیگیری تغییرات استفاده می‌کنیم، بنابراین باید یک حساب کاربری در آن‌جا ایجاد کنید. این راهنمای تنظیم gerrit را دنبال کنید

اساساً دو راه برای ارسال/کار با پچ‌ها وجود دارد. کسانی که با Git Review آشنا هستند می توانند از آن استفاده کنند، اما ما ابزار ساده‌تری به نام logerrit را توصیه می‌کنیم.

هنگام انجام تغییرات در زیرماژول‌هایی مانند help (و فقط شبیه سازی help) مراقب باشید زیرا اسکریپت logerrit در دسترس نیست و ممکن است gerrit hook را نصب نکرده باشید. برای مراحل راه‌اندازی، زیرماژول‌ها را ببینید.

اولین باگ خود را برای حل کردن پیدا کنید

تبریک می‌گوییم، به قسمت جالب کار رسیدید.

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

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

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

البته چالش‌های دیگری نیز برای بعد وجود دارد:

• همه اشکالات تأیید شده که در حال حاضر تخصیص داده نشده‌اند
• اشکالات حل نشده
• آزاردهنده‌ترین اشکالات

حل یک اشکال

برخی از توصیه‌های عملی بر اساس تجربه که توصیه می کنیم رعایت کنید عبارتند از:

• هرگز در شاخه master خود تغییراتی ایجاد نکنید - به جای آن یک branch ایجاد کنید.
• برای هر اشکال یک branch جداگانه نگه دارید و تا زمانی که رفع اشکال ادغام نشده است، branch را حذف نکنید.
• سبک کد را دنبال کنید (مانند طرح‌های نام‌گذاری متغیرها و غیره).
• اگر فایل‌های جدیدی ایجاد می‌کنید، لطفاً از سربرگ مجوز ما استفاده کنید.
• لطفاً فعلاً از قالب‌بندی مجدد بزرگتر کد خودداری کنید (به جز کارهایی که در زیر ذکر شده است) - ما در حال بررسی راه‌های خودکار/جادویی برای انجام این کار در میان‌مدت و بلندمدت هستیم.
• قبل از شروع یک باگ جدید، master را به‌روزرسانی کنید (و قبل از ایجاد هر گونه تغییری، Make check را اجرا کنید تا مطمئن شوید که قبل از این‌که تغییری بدهید کد درست کامپایل می‌شود)
• پچ‌هایی را که به یکدیگر وابسته هستند ارسال نکنید، مگر این‌که به شما گفته شود که این کار را انجام دهید. انجام این کار باعث می‌شود پچ شما قابل ادغام نباشد.
• اگر پچ شما آماده ادغام نیست، 2- را به آن اختصاص دهید، به این ترتیب بازبینی‌کنندگان می‌دانند که کار در حال انجام است.
• صبر در این کار کلیدی است، مرور زمان می‌برد و همه ما داوطلب هستیم، پس انتظار داشته باشید که چند روز بگذرد.

1. بروزرسانی شاخه master

مطمئن شوید که شاخه master شما به روز شده و کار می‌کند. اگر شاخه master شما خیلی قدیمی است، این خطر وجود دارد که نتوانید پچ خود را ادغام کنید.

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

• عمر شاخه master شما بیش از یک هفته است.
• رفع اشکال جدید شما به کارهایی بستگی دارد که به تازگی ادغام شده‌اند.

./g pull -r
make
make check

!! make باید 3.8.1 یا جدیدتر باشد.

لطفاً از گزینه r- استفاده کنید، که بسیار مؤثرتر از pull ساده است. master گاهی خراب می‌شود، اما این معمولاً فقط برای مدت کوتاهی اتفاق می‌افتد (معمولاً committer ها در صورت انجام اشتباه، سریع واکنش نشان می‌دهند).

وقتی make کامل شد، می‌دانید که یک شاخه master دارید که کار می‌کند، بنابراین اگر make هنگام کامپایل پچ شما خراب شد، به دلیل مشکل در جایی از کد شما است. make check همه test case ها را اجرا می‌کند و تضمین می‌کند که یک نسخه لیبره آفیس که کار می‌کند در دست دارید. اجرای ساده make قبل از make check هزینه‌ای برای ساخت شما ندارد و در صورت شکست تست، تضمین می‌کند که یک build دارید که اجرا می‌شود.

2. کار در یک شاخه

ممکن است بعداً از شما خواسته شود که تغییراتی در پچ خود ایجاد کنید، و اگر در یک شاخه جداگانه ایجاد کرده و کار کرده باشید، بسیار آسان خواهد بود. لطفاً برای هر اشکالی که روی آن کار می کنید از یک شاخه جدید (از master) استفاده کنید، پس از ادغام پچ می‌توانید شاخه را حذف کنید.

git checkout -b test1 origin/master

نام دلخواه خود را جایگزین test1 کنید.

3. اشکال را حل کنید

مشکل را شناسایی کنید، کد را تصحیح کنید، یک نسخه را تولید و آزمایش کنید. به خاطر داشته باشید که هر زمان ممکن است یک آزمون واحد ارائه دهید تا مطمئن شوید که مشکل حل شده است.

تعدادی ابزار مفید برای کمک به شما وجود دارد

• OpenGrok - از آن برای جستجو و مرور پایه کد استفاده کنید
• تبدیل آزمون واحد جاوا به پایتون
• وقایع‌نگار کامیت cgit
• بررسی اجمالی gerrit برای لیبره آفیس

به یاد داشته باشید که "git commit -a" را به طور منظم انجام دهید. این به شما این امکان را می دهد که به راحتی بخشی از توسعه خود را رها کنید، اگر مشخص شود که مسیر اشتباهی را در پیش گرفته بودید.

4. پچ را ارسال کنید

توصیه می شود که پیام‌های کامیت شما به شکل زیر باشد:

   tdf#12345 <short developer description of change, not just the bug title>
   <empty line>
   <description of what the patch does, the more words the better others understand it later>

• اگر گزارش اشکال مربوط به کامیت وجود دارد، اجباری است که خط اول را با یک مرجع اشکال مانند tdf#12345 شروع کنید (به جزئیات زیر مراجعه کنید)
• از بقیه خط اول به عنوان خلاصه‌ای مختصر از تغییرات خود استفاده کنید. حداکثر طول این خط 72 کاراکتر است.
• از زمان حال استفاده کنید. بگویید تغییر چه می‌کند. مختصر بنویسید. از «تزئینات» مانند خط تیره‌ها و کروشه‌هایی که فضا را هدر می‌دهند اجتناب کنید.
• اگر می‌خواهید متنی بیشتر از متنی که با خط اول مطابقت دارد ارائه دهید، خط دوم را خالی بگذارید.
• با شروع از خط 3 توضیح دهید که پچ چه کاری انجام می دهد و چرا، و اگر مشخص نیست همچنین چگونگی کار را شرح دهید. این خطوط حداکثر باید 80 کاراکتر داشته باشند. اگر نظر شما طولانی‌تر است، به چند خط تقسیم کنید. در این‌جا می‌توانید نحوه عملکرد نادرست کد قبل از تغییر را نیز توضیح دهید.

اگر پچ شما اشکالی را که قبلاً در باگزیلا ثبت شده را برطرف می‌کند، می‌توانید از اعلان‌های خودکار خطا که توسط پیام‌های کامیت راه‌اندازی می‌شوند، استفاده کنید: وقتی اولین خط پیام کامیت حاوی یک مرجع باشد. به یک اشکال به شکل tdf#12345، سپس زمانی که تغییر به مخزن push می‌شود، یک نظر مرتبط به طور خودکار به گزارش اشکال اضافه می‌شود. برای جزئیات بیشتر رشته اعلان را در mail-archive.com یا در fdo-listarchive ببینید.

بررسی کنید که تغییرات شما آزمون‌های خودکار را خراب نمی‌کند:

make check

اکنون می‌توانید پچ را به gerrit ارسال کنید (به آماده شدن برای ارسال پچ‌ها مراجعه کنید):

./logerrit submit master

بررسی پچ شما

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

به طور کلی 3 چیز می‌تواند در بررسی اتفاق بیفتد:

• کامیت کننده پچ را با موفقیت بررسی و آزمایش کرد، سپس آن را ادغام کرد (تبریک)
• کامیت کننده نظراتی داشته، که باید به آن‌ها نگاه کنید
• گاهی اوقات پچ برخی از عملکردهای دیگر را خراب می‌کند و به عنوان «نمی‌توان ادغام کرد» علامت‌گذاری می‌شود

در دو حالت اخیر، باید پچ خود را به روز کنید.

For more on the patch review process, see Development/gerrit/PatchReview.

به‌هنگام‌سازی یک پچ

شاخه خود را checkout کنید،

git checkout test1

تغییرات مورد نیاز را انجام دهید و آن‌ها را آزمایش کنید. مؤدبانه است که در مورد خطوط کدی را که نمی‌خواهید تغییر دهید یا در جایی که با commit کننده موافق نیستید نظر دهید، این کار مستقیماً در gerrit انجام می‌شود.

هنگامی که برای کامیت دوباره آماده شدید، مهم است که از amend-- استفاده کنید

git commit --amend -a

مهم از پارامتر m- استفاده نکنید زیرا شناسه پچ gerrit را پاک می‌کند. اجازه دهید git یک ویرایشگر را باز کند و به شما امکان می‌دهد پیام کامیت را ویرایش کنید (یا آن را بدون تغییر رها کنید). هنگام ویرایش مراقب باشید آخرین خط با شناسه پچ را حذف نکنید یا تغییر ندهید.

این به شما اطمینان می‌دهد که به جای ایجاد پچ جدید (با :Change-Id) پچ را به روز می‌کنید.

پچ جدید را روی gerrit آپلود کنید

./logerrit submit master

بیانیه مجوز

ما می‌خواهیم کد منبع را برای استفاده هر کسی آزاد نگه داریم، بنابراین مهم است که یک بیانیه مجوز را به libreoffice@lists.freedesktop.org (لطفاً از موضوع: <نام شما> بیانیه مجوز استفاده کنید). با متن زیر ارسال کنید:

   All of my past & future contributions to LibreOffice may be
   licensed under the MPLv2/LGPLv3+ dual license.

It is important to make sure that the mail allows connecting the statement to the contributions, so send the statement from the same email that is used in your commits.

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

لطفاً بیانیه را زودتر از زمانی که اولین ارسال خود را به gerrit ارسال می کنید، ارسال نکنید. اگر زیر سن قانونی هستید، از والدین یا قیم قانونی خود بخواهید که ایمیل را ارسال کنند (همه افرادی که سرپرستی دارند).

اگر با آثار هنری همراه با نرم‌افزار (مانند نمادها) همکاری می‌کنید، این را به ایمیل بیانیه مجوز خود اضافه کنید:

   Additionally, to the extent possible under law, I waive all
   copyright and related or neighboring rights to my past & future
   Artwork and Design contributions to the LibreOffice project, and
   similarly to The Document Foundation, placing such contributions
   under CC0: https://creativecommons.org/publicdomain/zero/1.0

تبریک

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

به ساختن پچ‌ها ادامه دهید، و به زودی خودتان یک commit کننده خواهید شد.

نقشه راه برای رشد شخصی

یک برنامه‌نویس برای این‌که بتواند روی کد لیبره آفیس کار کند باید مهارت/تجربه‌های مشخصی داشته باشد. این مسیری است که برای هر کسی که می‌خواهد در توسعه لیبره آفیس مشارکت کند پیشنهاد می‌شود:

1. درک سطح متوسط ++C بدست آورید: بیشتر کدهای لیبره آفیس به زبان ++C هستند، بنابراین برای این‌که بتوانید با کد کار کنید باید به ++C مسلط باشید.
2. git و gerrit را درک کنید: git نرم‌افزار کنترل نسخه است که در لیبره آفیس استفاده می‌شود. شخص باید git و gerrit را درک کند تا بتواند مشارکت کند
3. قادر به build لیبره آفیس باشید: برای این‌که بتوانید کد را تغییر دهید، باید بتوانید لیبره آفیس را از روی کد منبع بسازید.
4. حداقل 10 تریاژ اشکال انجام دهید: برنامه‌نویسان باید باگزیلا و گردش کار مرتبط با اشکالات و ویژگی‌های نرم‌افزار را درک کنند. این برای ادامه کار ضروری است.
5. حداقل 5 هک آسان با درجه دشواری مبتدی (++C) انجام دهید: این اولین گام برای درک و تغییر کد است.
6. حداقل 5 هک آسان با درجه دشواری متوسط (++C) انجام دهید: پس از انجام چند کار ساده‌تر، مهم است که بتوانید کارهای جدی‌تری انجام دهید.
7. حداقل 1 هک آسان با درجه دشواری جالب انجام دهید
8. حداقل 5 اشکال رگرسیون را حل کنید: رگرسیون‌ها معمولاً به راحتی قابل بازتولید هستند و می‌توانند در مدت زمان معقولی رفع شوند، بنابراین برای تازه‌واردان مناسب هستند.
9. به تعداد مشخصی از کامیت برسید (60~)
10. حداقل 1 هک هسته انجام دهید

آداب تازه‌کاران

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

دستورالعمل‌های عمومی:

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

اگر با مشکلی با "git، ارسال پچ یا راه‌اندازی محیط برنامه‌نویسی" مواجه هستید، بهتر است این مراحل را دنبال کنید:

1. سعی کنید چگونگی یا راه‌حل را خودتان جستجو کنید. گاهی اوقات کمک‌کنندهای شما نیز باید جستجو کنند.
2. اگر جستجوی شما موفقیت آمیز بود، سعی کنید دستورالعمل‌ها را دنبال کنید.
3. اگر هیچ دستورالعملی پیدا نکردید یا در اجرای آن‌ها به مشکل بر خوردید، کمک بخواهید.

با این نوع مسائل، کمک کنندگان کاملاً خوشحال هستند که سعی می کنند کل مشکل شما را برای شما حل کنند.

اگر در حال حل یک هک آسان هستید، خوب است این حقایق و نکات را در ذهن داشته باشید:

• هیچ سند واحدی مبنی بر توضیح پایه کد به صورت مشروح وجود ندارد. مطالب آموزشی در اسلایدهای ارائه کنفرانس، پست‌های وبلاگ و صفحات ویکی پراکنده شده است.
• فراوانی نظرات کد کمتر از حد ایده‌آل است (شما می‌توانید کمک کنید!)، بنابراین باید برای خواندن کد آماده باشید.
• برای یافتن تعاریف توابع و کلاس هایی که با آن‌ها برخورد می کنید از git grep، IDE و OpenGrok استفاده کنید.
• تاریخچه commit را نیز برای موضوعات مشابه در جاهای دیگر در پایگاه کد بررسی کنید. دستور Annotate در OpenGrok می‌تواند برای این نوع بررسی‌هایی آشکارگر باشد.
• در حالی که از لیبره آفیس استفاده می‌کنید از یک دیباگر بهره بگیرید تا بفهمید درون نرم‌افزار چه می‌گذرد
• پرونده‌های readme را مرور کنید.

اگر از کسی بخواهید بگوید چگونه می‌توان چیزی را پیاده‌سازی کرد، احتمالاً با سکوت روبرو خواهید شد. هک‌های آسان قرار است یک تجربه یادگیری باشند و مربیان نمی‌خواهند آن را خراب کنند. در مورد پیاده‌سازی پیشنهادی در سامانه بازبینی ارسال‌ها اظهار نظر خواهد شد.