Zhvillimi/Përfshihu

    From The Document Foundation Wiki
    This page is a translated version of the page Development/GetInvolved and the translation is 41% complete.


    Zhvilluesit dhe përdoruesit mund të kontribuojnë në zhvillimin e LibreOffice në shumë mënyra dhe të gjithë janë të mirëpritur në projekt.

    Në këtë faqe ne përqendrohemi te zhvilluesit. Ne jemi të hapur për të gjitha nivelet e zhvilluesve. LibreOffice është një nga paketat më të mëdha, më të vjetra dhe më të njohura (si OpenOffice) të softuerit falas. Nëse jeni student ose kërkoni punë zhvillimi, po të shkruani në CV-në tuaj "Unë kam punuar për LibreOffice" është një plus i madh. Zhvilluesit ndihmojnë në përmirësimin e bazës së kodit të LibreOffice. Në fillim, baza e madhe e kodit mund të jetë frikësuese, por dokumentacioni po përmirësohet dhe do të merrni ndihmë nga ekipi ekzistues i zhvilluesve. Kjo faqe do t'ju ndihmojë të dërgoni arnën tuaj të parë. Për të ndihmuar në marrjen e një pasqyre të përgjithshme:

    Udhëzues hap pas hapi për zhvilluesit e rinj

    Është e lehtë të mbytesh nga madhësia dhe kompleksiteti i LibreOffice. Burimi është shkruar në shumë gjuhë dhe formate të ndryshme — C, C++, Java, Bash, JavaScript, Python, Perl, SQL, XML — dhe përbëhet nga afërsisht 102,000 skedarë (duke përjashtuar të gjitha lokalizimet) me 36,000,000 rreshta teksti (7,000,000 rreshta kodi burimor).

    Askush nuk e kupton të gjithë kodin në detaje, por ne kemi shumë zhvillues kryesorë që secili e di një pjesë të kodit në detaje. Ky udhëzues hap pas hapi tregon një mënyrë të thjeshtë duke shkuar nga "dëshira për të kontribuar", për të bashkuar me sukses arnën e parë në master.

    Lidhu me kanalet tona të komunikimit

    Our mailing list is libreoffice@lists.freedesktop.org; we recommend you subscribe to it. You can also follow the list online.

    For real-time chat we use IRC at the Libera Chat network #libreoffice-dev IRC://

    Ndërto LibreOffice

    Për të bërë zhvillimin, ju duhet një kopje lokale e kodit burimor. I gjithë kodi mbahet në git. Klonimi i kodit burim shpjegohet në artikujt e udhëzimeve të ndërtimit për çdo sistem operativ.

    Dritare (Windows)

    Zhvilluesit e Windows kanë nevojë për të instaluar Cygwin dhe shërbime të tjera. Mënyra më e lehtë është të përdorni Mjedisin e Zhvillimit të LibreOffice (LODE). Udhëzime të detajuara të ndërtimit të Windows janë gjithashtu të disponueshme.

    macOS

    Ne sugjerojmë të ndiqni udhëzimet që përdorin Mjedise të Zhvillimit të LibreOffice (LODE). Më shumë informacion dhe detaje rreth Xcode mund të lexoni në artikullin Ndërtimi i LibreOffice në macOS.

    Linux

    Linux (shumica e distribucioneve) mund të konfigurohet duke përdorur instaluesit e paketave. Ne ju sugjerojmë të ndiqni Ndërtimi në Linux

    Përgatituni për të paraqitur arna

    Once you have successfully compiled LibreOffice you are ready to submit patches. We use gerrit to keep track of patches, so you need to create an account there. Follow this gerrit setup guide

    Në thelb ekzistojnë dy mënyra për të paraqitur/punuar me arna. Ata që janë të njohur me Rishikimi i Git mund ta përdorin atë, por ne rekomandojmë një mjet më të thjeshtë të quajtur logerrit.

    Jini të kujdesshëm kur kryeni ndryshime në nënmodule si ndihma (dhe vetëm ndihma e klonimit) pasi skripti logerrit nuk është i disponueshëm dhe mund të mos e keni të instaluar grepin gerrit. Për hapat e konfigurimit, shihni Zhvillimi/Nënmodulet.

    Gjeni bug-un tuaj të parë për të zgjidhur

    Urime, keni arritur në pjesën interesante.

    Solving the first bug involves learning new tools and ways, therefore we have identified some easy bugs called Easy_Hacks. We use bugzilla where you need to create a account, to keep track of reported bugs.

    Hakimet e lehta janë buge të vërteta, por zhvilluesit kryesorë kanë shtuar tregues të kodit burimor dhe ndonjëherë ndihmë tekstuale, në vend që thjesht t'i zgjidhin ato, për ta bërë më të lehtë për ju zgjidhjen e bugeve. Zgjidhni një bug nga gjuha juaj e preferuar e programimit (shih sipër) që ju intereson EasyHacks sipas gjuhës dhe aftësive, pasi e shihni që ka shumë për të zgjedhur. Ne ju rekomandojmë të zgjidhni një nga kategoria "Niveli i aftësive: fillestar", për t'ju lejuar të përqendroheni në të gjitha "si mund të ...".

    Once you have selected a bug to solve, please do not forget to assign it in bugzilla to yourself, so others can see you are working on it. If you want to work on one of the general bugs (like converting foo to xyz), then please do not assign it to you, since many can work on that in parallel. The EasyHacks are monitored so if there are no progress after a time we will unassign it.

    Sigurisht që ka edhe sfida të tjera për më vonë:

    Zgjidhja e një bug-u

    Disa këshilla praktike, bazuar në përvojën, të cilat ju rekomandojmë t'i ndiqni janë:

    • Asnjëherë mos bëni ndryshime në kopjen tuaj të masterit - në vend të kësaj krijoni një degë(branch).
    • Mbani një degë të veçantë për çdo gabim dhe mos e fshini degën derisa korrigjimi i bugeve të bashkohet.
    • ndiqni |Stili i kodit (siç janë skemat e emërtimit të variablave, etj.).
    • Nëse krijoni skedarë të rinj, ju lutemi përdorni Titulli i licencës.
    • Ju lutemi, shmangni për momentin një riformatim më të madh të kodit (përveç detyrave të listuara më poshtë) - ne jemi duke menduar për mënyrat automatike/magjike për ta bërë këtë në afate të mesme dhe afatgjatë.
    • Përditësoni masterin përpara se të filloni me një defekt të ri (dhe ekzekutoni bëj kontroll për të konfirmuar se ai përpilohet pastër përpara se të bëni ndonjë ndryshim).
    • Mos paraqisni arna që varen nga njëra-tjetra, përveç nëse ju thuhet ta bëni këtë. Duke vepruar kështu, arna juaj do të jetë i paaftë për t'u bashkuar.
    • Nëse arna juaj nuk është gati për t'u shkrirë, caktoni -2 në të, në këtë mënyrë rishikuesit e dinë se është Punë në Progres.
    • Durimi është një çelës, rishikimi kërkon kohë dhe ne jemi të gjithë vullnetarë, ndaj prisni që të kalojnë disa ditë.

    Rrjedha e sugjeruar e punës

    1. Përditëso master

    Sigurohuni që masteri juaj është i përditësuar dhe funksionon. Nëse masteri juaj është shumë i vjetëruar, ju rrezikoni të mos jeni në gjendje të bashkoni patch-in tuaj.

    Si rregull, përdorni komandat e mëposhtme nëse:

    • Masteri juaj është më shumë se një javë.
    • Rregullimi juaj i ri i defekteve varet nga puna që sapo është bashkuar.

    ./g pull -r
    make
    make check

    !! make duhet të jetë 3.8.1 ose më e lartë.

    Ju lutemi përdorni çelësin '-r, i cili është shumë më efektiv sesa thjesht tërheqja. Masteri prishet shpesh, por normalisht vetëm për një kohë të shkurtër (angazhuesit zakonisht reagojnë shpejt nëse bëjnë një kryerje të gabuar)

    Kur make përfundon, ju e dini që keni një master që punon, kështu që nëse make prishet gjatë përpilimit të patch-it tuaj, kjo është për shkak të një problemi diku në kodin tuaj. ""bëj kontroll"" ekzekuton të gjitha rastet e provës dhe siguron që të kesh një version funksional të LibreOffice. Ekzekutimi i thjeshtë make përpara bëj kontrollin nuk ju kushton kohë ndërtimi dhe në rastin e dështimeve të provës, ju siguron që të keni një ndërtim që funksionon.

    2. Puna në një degë

    Më vonë mund t'ju kërkohet të bëni ndryshime në patch-in tuaj, dhe nëse keni krijuar dhe punuar në një degë të veçantë, kjo do të jetë shumë e lehtë. Ju lutemi përdorni një degë të re (nga origjina/master) për çdo defekt me të cilin punoni, pasi të jetë bashkuar patch-i, mund ta fshini degën.

    git checkout -b test1 origin/master

    Zëvendësoni test1 me emrin tuaj të preferuar.

    3. Zgjidh defektin

    Identifikoni problemin, korrigjoni kodin, krijoni dhe provoni një version. Mos harroni të jepni një test-njësi sa herë që është e mundur për të verifikuar që problemi është zgjidhur.

    There are a number of handy tools to help you

    Mos harroni të bëni rregullisht 'git commit -a. Kjo ju jep mundësinë që të braktisni lehtësisht një pjesë të zhvillimit tuaj, nëse rezulton se është një rrugë e gabuar.

    4. Paraqisni patch-in

    It is recommended that your commit messages look like:

       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>
    
    • 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:

    make check

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

    ./logerrit submit master


    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.

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

    Updating a patch

    Checkout your branch,

    git checkout test1

    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

    git commit --amend -a

    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

    ./logerrit submit master

    License statement

    We want to keep the source code free for use by anybody, therefore it is important that you mail (please use Subject: <your name> license statement) a license statement to libreoffice@lists.freedesktop.org with the text:

       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.

    A slight variation to suit your personal taste is fine as long as the intention is clear. 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


    Beginner etiquette

    Experienced contributors will help you find solutions to your problems, but there are expectations and limits. Remote mentoring and troubleshooting has a greater cognitive load compared to being physically present. Showing you are well-prepared makes people more motivated to help you.

    General guidelines:

    • When using the chat, immediately describe your problem and stay in the channel for at least an hour.
    • For sharing text with multiple lines in the chat, use a paste service such as the one mentioned in the channel topic.
    • If you have network connection issues, the mailing list works better than the chat.
    • If you are doing a complex multi-step task, it is a good idea to keep personal notes. These will come in handy when you are asked what you did so far.
    • After receiving a reply, acknowledge it somehow. If you disappear without a trace, your helpers will feel distressed.

    If you are facing an issue with git, patch submission or setting up the development environment, it is best to follow these steps:

    1. Try to search for the how-to or solution yourself. Sometimes your helpers have to search as well.
    2. If your search was successful, make an attempt to follow the instructions.
    3. If you did not find any instructions or got stuck applying them, ask for help.

    With these types of issues, helpers are quite happy to try and solve your entire problem for you.

    If you are solving an easy hack, it is good to keep these facts and tips in mind:

    • There is no single document explaining the code base in prose. Educational material is scattered across conference presentation slides, blog posts and wiki pages.
    • The frequency of code comments is less than ideal (you can help!), so you should be prepared to read code.
    • Use git grep, an IDE and OpenGrok to find the definitions of the functions and classes you run into.
    • Investigate the commit history, also for similar topics elsewhere in the code base. OpenGrok's Annotate command can be revealing for this type of detective work.
    • Run a debugger while using LibreOffice to find out what is going on under the hood.
    • Browse the readme files.

    If you ask someone to say how to implement something, you will probably be faced with silence. Easy hacks are supposed to be a learning experience and mentors do not want to ruin it. A proposed implementation will be commented on in the review system.