- 1 Step-by-step guide for new developers
- 1.1 Connect to our communication channels
- 1.2 Build LibreOffice
- 1.3 Prepare to submit patches
- 1.4 Find your first bug to solve
- 1.5 Solving a bug
- 1.6 Congratulations
- 2 Beginner etiquette
Developers and users can contribute to the LibreOffice development in many ways and everyone is welcome in the project.
Users can, for instance, help the development by testing beta releases of the software, reporting and testing of bugs, writing documentation, contributing to templates, update thesaurus, dictionaries, translate to your native language, add art work, spreading the word and promote LibreOffice.
On this page we concentrate on developers. Bear in mind we are open to all levels of developers, we have a few "core" developers (this basically means people who have been around since history started) but most of us are relatively new. LibreOffice is one of the biggest, oldest and most known (as OpenOffice) free software packages. If you are a student or looking for development work, being able to write "I have worked for LibreOffice" is a great plus on your CV. You can, after agreement, use our Development Mentoring Lead as a reference. Developers help to improve the LibreOffice code base. At first, the enormous code base can be intimidating, but documentation is improving and you will receive assistance by the existing developers team. This page will help you get your first patch submitted. To help get an overview (remember all easyHacks have code pointers):
- Graphic code overview
- Documentation on specific modules
- How to Create a Custom Widget?
- DrawingLayer: What should you Know about it?
- Frequently Asked Questions
Step-by-step guide for new developers
Nobody understands the whole code in detail, but we have many core developers who each know part of the code in detail. This step by step guide shows an easy way going from "wanting to contribute" to successfully have the first patch merged to master. If you want help or need more information, please do not hesitate to contact our Development mentor
Connect to our communication channels
Our main communication channel is firstname.lastname@example.org; we recommend you subscribe to it. You can also follow the list online at http://nabble.documentfoundation.org. How to use the development mailing list
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 email@example.com 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 and ensure you have permission from your parents!
If you need a quick response to a simple question, you can find many of us on IRC freenode connect via webchat
In order to do development you need a local copy of the source code. All code is kept in git
Windows developers need Cygwin and other utilities installed. The easiest way is to use lode
Remark some people experience problems with the directory names in windows (like LO cannot find the mscvc.exe), please have a look here:
a word about antivirus scanners
When you build we highly recommend you deactivate your virus scanner (and of course no surfing while deactivated).
If you leave the virus scanner active you must add an exception list containing at least
- <git home>/workdir
otherwise the build will fail. We have noticed that running a virus scanner whilst building often increases build time, sometimes by more than 30%.
In some cases it is a problem with real-time protection of running application.
The trouble here is, AV scanning the running application and when the compile try to generate the next test-tool (with same test-name) the linker can't write the file, because the AV scanner block this file. AV it is slower as the test-tool is running.
There has been reported several issues during installation relating to the virus scanner, so it is highly recommended to disable the virus scanner while running lode.
macOS can be setup in different ways, as you get more specialized you might want a more complicated setup, but to get started we suggest to follow Quick Setup
Linux (most flavors) can be set up using the package installers. We suggest you follow Building on Linux
Prepare to submit patches
There are basically two ways to submit/work with patches. Those familar with Git review can use that, but we recommend a simpler tool called
Be careful when committing changes to submodules like help (and only cloning help) as the logerrit script is not available and you might not have the gerrit hook installed. For setup steps, see Development/Submodules.
Find your first bug to solve
Congratulations, you have reached the interesting part.
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.
Easy hacks are real bugs, but the core developers have added source code pointers and sometimes textual help instead of simply solving them, to make it easier for you to solve the bug. Select a bug from your favorite programming language (see above) that interest you EasyHacks by language and skill, as you see there are plenty to choose from. We recommend you choose one from the category "Skill level: beginner", to allow you to concentrate on all the "how do I ....".
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.
Of course there are also other challenges for later:
Solving a bug
Some practical advice, based on experience, which we recommend that you follow is:
- Never make changes to your copy of master - create a branch instead.
- Keep a separate branch for each bug, and do not delete the branch until the bug-fix is merged.
- follow the Code Style (such as variable naming schemes, etc.).
- If you create new files, please use our License Header.
- Please avoid larger reformatting of the code for the time being (except for the tasks listed below) - we're pondering auto/magic ways to do that mid- to long-term.
- Update master before starting on a new bug (and run make check to confirm it compiles cleanly before you make any changes).
- Do not submit patches that depend on each other, unless being told to do so. Doing so will make your patch incapable of being merged.
- If your patch is not ready to be merged, assign -2 to it, that way reviewers know it is Work In Progress.
- Patience is a key, reviewing takes time and we are all volunteers, so expect a couple of days to pass.
1. Update 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:
- your master is more than a week old.
- your new bug-fix depends on work that just got merged.
./g pull -r make make check
!! make must be 3.8.1 or higher.
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.
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.
git checkout -b test1
Replace test1 with your preferred name.
3. Solve the bug
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 <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:
Now you can submit the patch to gerrit (see Prepare to submit patches):
./logerrit submit master
Review of your patch
Your patch will typically be reviewed within 1-2 days. You can follow the progress in gerrit and you will also receive mail whenever there is a change. (Don't be too concerned if Jenkins reports that only the Windows build failed the automated compiling.)
In general 3 things can happen in the review:
- The committer reviewed and tested the patch successfully, then merged it to master (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 2 later cases, you need to update your patch.
If you look at your patch on Gerrit you will see two status codes:
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
-2 are to be used by the author, to signal "work in progress". The -2 prevent 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
-1 is used by the CI system if the build fails (remark 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 succesfull
+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 successfull build.
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
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.
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.
- 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:
- Try to search for the how-to or solution yourself. Sometimes your helpers have to search as well.
- If your search was successful, make an attempt to follow the instructions.
- 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 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.