Development/GetInvolved/fa

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

1. بروزرسانی شاخه master
Make sure your master is updated and works. If your master is too outdated, you run the risk of not being able to merge your patch.

As a rule of thumb, use the commands below if: !! make must be 3.8.1 or higher.
 * your master is more than a week old.
 * your new bug-fix depends on work that just got merged.

Please use the -r switch, which is far more effective than simply pulling. Master is frequently broken, but normally only for a short time (committers normally react fast if they make a wrong commit).

When make completes you know you have a working master, so if make breaks while compiling your patch it is due to a problem somewhere in your code. make check runs all test cases and ensures you have a working version of LibreOffice. Running plain make before make check does not cost you build time and in the case of test failures, it ensures you have a build that runs.

2. Work in a branch
You might be asked later to make changes to your patch, and if you have created and worked in a separate branch that will be very easy. Please use a new branch (from master) for every bug you work on, once the patch has been merged you can delete the branch.

Replace test1 with your preferred name.

۳. باگ را رفع کنید
Identify the problem, correct the code, generate and test a version. Remember to supply a unit-test whenever possible to verify that the problem is solved.

There are a number of handy tools to help you
 * OpenGrok - use it to search and browse the code base
 * Convert java unit-test to python
 * cgit commit log
 * gerrit overview for LibreOffice

Do remember to do git commit -a regularly. This gives you the possibility to easily abandon part of your development, should it turn out to be a wrong path.

4. Submit the patch
It is recommended that your commit messages look like: tdf#12345  


 * if there is a bugreport related to the commit, it's mandatory to start the first line with a bug reference like tdf#12345 (see details below)
 * use the rest of the first line as a concise summary of your changes. The maximum length for this line is 72 characters.
 * use present tense. tell what the change does. be terse. avoid "decorations" like dashes and brackets that waste space.
 * if you want to provide more text than what fits the 1st line, it's mandatory to leave the 2nd line empty
 * starting from the 3rd line explain what the patch does and why, and if it not obvious also how. These lines should have 80 characters length at most; split into several lines, if your comment is longer. Here you can also describe how the code used to work incorrectly before the change.

If your patch fixes a bug that is already filed in Bugzilla, then you can take advantage of automatic bug-notifications that are triggered by commit-messages: When the first line of the commit message includes a reference to a bug in the form tdf#12345, then a corresponding comment will automatically be added to the bugreport, when the change is pushed to the repository. See the announcement-thread on mail-archive.com or on fdo-listarchive for more details.

Verify that your changes don't break automated testing:

Now you can submit the patch to gerrit (see Prepare to submit patches):

Review of your patch
In the case of easy hacks, add the person who provided the code pointers as a reviewer for your patch. You will receive an email whenever there is a change in your patch.

In general 3 things can happen in the review:


 * The committer reviewed and tested the patch successfully, then merged it (congratulations)
 * The committer had some comments, which you need to look at
 * Sometimes the patch breaks some other functionality and is marked as “Cannot merge”

In the latter two cases, you need to update your patch.

Use of and
If you look at your patch on Gerrit you will see two status codes:


 * Code-Review
 * Verified

The reviewers, our CI system (jenkins) and potentially yourself will use these two fields to qualify the patch.

Can be assigned −2, −1, 0, +1, +2
 * Code-Review

−2 are to be used by the author, to signal “work in progress”. The −2 prevents the patch from being merged, and only the person who issued the −2 can remove it.

If you work on a larger patch, you are most welcome to upload a patch, mark it as −2, to see if it builds successfully on all platforms

−1 is used by the reviewer, if there are things in the patch that should be changed

0 is used when making comments, that has no effect on whether or not the patch should be merged.

+1 is used by the reviewer, to signal the patch is ok, but the reviewer would like a second opinion

+2 is used by the author to signal no review is needed (this can only be done by core developers, and should be used with care). The person who merges your patch, will use +2, just before merging, since only +2 can be merged. The ability to set +2 depends on the push rights of the reviewer. These rights are conferred individually.

Remark, a patch will NOT be merged as long as there are −1 or −2 unresponded to.

Can be assigned −1, 0, +1
 * Verified

−1 is used by the CI system if the build fails (note that this is not always a problem in your patch, but can be due to a broken master).

−1 is used by the reviewer, if the expected result cannot be seen.

0 is used when making comments, that has no effect on whether or not the patch should be merged.

+1 is used by the CI system if the build is successful

+1 is used by the reviewer, when the expected result has been verified.

Remark, a patch will NOT be merged unless the CI system shows a successful build.

Updating a patch
Checkout your branch,

make the needed changes and test them. It is polite to comment the lines of code you do not want to change or where you do not agree with the committer, this is done directly in gerrit.

Once you are ready to commit again it is important you use --amend

Important do not use the -m parameter as it will wipe out the gerrit patch id. Let git open an editor, allowing you to edit the commit message (or leave it unchanged). When editing be careful not to remove/modify the last line with the patch id.

This will ensure you update the patch, instead of generating a new one (with a new Change-Id:).

Upload the new patch set to gerrit

License statement
We want to keep the source code free for use by anybody, therefore it is important that you mail (please use Subject: license statement) a license statement to [mailto:libreoffice@lists.freedesktop.org libreoffice@lists.freedesktop.org] with the text: All of my past & future contributions to LibreOffice may be   licensed under the MPLv2/LGPLv3+ dual license. A slight variation to suit your personal taste is fine as long as the intention is clear. You will receive a welcome message in response. We keep a list of developers in our wiki.

'''Please only send the statement no earlier than when you post your first submission to gerrit. If you are underage, ask your parents or legal guardians to send the email (all persons having guardianship).'''

If you will be contributing artwork that will be included with the software (such as icons), add this to your license statement email: 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

Congratulations
You have successfully made a change to one of the most popular open-source packages in the world.

Continue to make patches, and you will soon be a committer yourself.

Roadmap for personal growth
A developer needs to have specific skills/experience in order to be able to work on LibreOffice Code. This is the path suggested for anyone who wants to get involved in LibreOffice development:


 * 1) Understand intermediate level C++: Most of the LibreOffice code is in C++, so one should be fluent with C++ in order to be able to work with the code.
 * 2) Understand git and gerrit: git is the version control software that is used in LibreOffice. One should understand git and gerrit in order to be able to contribute
 * 3) Be able to build LibreOffice: To be able to change the code, one should be able to build LibreOffice from the sources.
 * 4) Do at least 10 bug triages: Developers should understand Bugzilla and the workflow associated with bugs and features. This is essential in order to be able to proceed.
 * 5) Do at least 5 EasyHacks with difficulty beginner (C++): The first step towards being able to understand and change the code.
 * 6) Do at least 5 EasyHacks with difficulty medium (C++): After doing some easier tasks, it is important to be able to do some more serious work.
 * 7) Do at least 1 EasyHacks with difficulty interesting
 * 8) Fix at least 5 regressions: Regressions are usually easy to reproduce, and can be fixed in a reasonable amount of time, so they are suitable for the newcomers
 * 9) Reach certain number of commits (~60)
 * 10) Do at least 1 CoreHack

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

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


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

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


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

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

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


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

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