- 1 How to get involved
- 1.1 Reporting Bugs
- 1.2 Finding a first task: Easy Hacks
- 1.3 Lists of enhancements and missing features
- 1.4 Preparing patches
- 2 General Programming Guidelines
How to get involved
Developers and users can contribute to the LibreOffice development in many ways and everyone is welcome in the project. Users, for instance, can help the development by testing beta releases of the software, reporting and testing of bugs, writing documentation, contributing to templates, art work, thesaurus, dictionaries, etc. and last but not least promoting LibreOffice.
Developers can 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. To get started there is:
- an overview of LibreOffice: see the Code Overview page to help you get a grasp what the directories are for (with further links to cgit and doxygen)
- also a list of Frequently Asked Questions.
- OpenGrok, which can be used to search and browse the code base
- the stream of commits can be seen at:
Reporting bugs to the LibreOffice Bugtracker, verifying them and test whether issues still exist in newer versions of LibreOffice, are valuable contributions to the project. Here is information on how to submit new bugs.
Finding a first task: Easy Hacks
In order to set the entry barrier for new contributors as low as possible, the LibreOffice team has collected a list of Easy Hacks. It's purpose it to help you find a first task. For a general introduction, see Michael Meeks slides for the Easy Hacks Talk at FOSDEM 2012. Please note that any bug assigned to firstname.lastname@example.org is unassigned (this is our default).
Of course there are also other bugs/enhancements in the bugtracker:
- All Confirmed Bugs Not Currently Assigned
- Open issues
- Most annoying bugs (3.6)
- Most annoying bugs (3.5)
- Most annoying bugs (3.4)
Lists of enhancements and missing features
Besides the Easy Hacks Wiki page, several other lists of enhancements and missing features have been created:
- There is a list of Crazy Ideas that contain disruptive changes as well as other missing features.
- A page dedicated to missing features and enhancements that are related to the special needs of large corporations, where IT management has some challenges in deployment and support. We listed in this page what enterprises have already told us they love to have in LibreOffice. If you want your boss happy, help us to fix these!
- A page to collect ideas for improvements to the default user experience, has been started on Default UI Improvements.
- A page which lists Really basic missing features and enhancements.
- A list where users express their need for certain enhancements has been set up: Vote for Enhancement.
First of all, it would make sense to follow the OpenOffice.org Coding Style and general code conventions (such as variable naming schemes, etc). To prepare a patch that you can send to the developers, you best
- start with a unmodified master branch
- Hack the code to your hearts content (if you plan something bigger, consider using feature branches)
- commit your changes locally
Commiting your changes locally
To commit your changes locally to git, you first have to declare what to include. Here are two ways to do that:
- This one adds all modified files:
git commit -a
git add file1 file2allows you to explicitly select the files to include. see the Pro Git Book for the details.
to locally commit your changes. When you type a commit message:
- start the first line with a bug reference like fdo#12345, if you have one for your commit (see details below)
- use the rest of the first line as a concise summary of your changes
- the 2nd line remains empty
- and starting on the 3rd line you can explain how and what changes have been made for what reasons.
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 fdo#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.
After commiting your change locally you have three options:
Sending patches directly to gerrit.libreoffice.org
which will upload your local commit to gerrit. All the gory details are here.
Alternative: Sending patches manually to the mailing list
Alternatively, you can go oldschool and read these notes on how to use the development mailing list and then:
- create the patch file that you want to mail. If you are in one repository you can use git directly to get e.g. the last change in your branch as a diff file with:
git format-patch HEAD~1
If you have made more wide sweeping changes across multiple repositories you can get those patches for all those repositories in one go with:
./g format-patch --suffix=.@REPO@.patch -o/home/me/somedir/to_save_my_patches_in origin/master..HEAD
- create a mail to the development list and attach those patch files to your email.
- Use a subject line of the form: "[PATCH] fdo#<bug number>: <Bug title>". For example: "[PATCH] fdo#43398: FORMATTING: Documents opened in LibreOffice Writer incorrectly appear as right justified".
- after sending in your patch, if you want to go back to the regular upstream master, you can use the command:
or these manual instructions to get back to a prestine copy.
Please refer to the Patch Handling Guideline page for more detailed patch handling rules and workflow to make our patch integration process as efficient and painless as humanly possible.
Alternative: Offer git branches to pull from
LibreOffice being developed using git means of course that we can use all the wonderful features that git offers. E.g. people can prepare a cloned git branch that committers can pull patches from. If you plan to do that, it might be wise to coordinate with a committer in advance whether he feels comfortable in doing so.
General Programming Guidelines
Getting your first successful build of LibreOffice can be an intimidating and daunting task. Find a walkthrough that should guide you towards getting your first build finished on the How to Build page.
If you want to compile LibreOffice without GUI support (e.g. for servers) you can find additional information on the headless build page.
Git is a Distributed Version Control System (DVCS). It is a very powerful yet simple system, but if you are unfamiliar with DVCS, it can be confusing. Thankfully there are great resources on the Web to learn about Git. If you are not familiar with it, you should visit http://git-scm.com/ .
Most of LibreOffice source code is in the 'core' git repository, but few modules are in separate repository: 'translations', help', 'dictionaries' and 'binfilter'. In most cases you probably won't have to modify these repositories, but if you do you might want to read Git For LibreOffice Developers about the ./g tool that should help you to make this a bit less painful.
Getting and using commit access
In order to get commit access you need to be "sponsored". Once you've submitted patches and got yourself recognised this won't be a problem, but it's best to wait until you're asked. Once you've been asked (or asked for someone to sponsor you), you need to get an account
sal_Bool should be used only when it comes to UNO, and bool is preferred otherwise. More elaborate guidelines can be found:
- The OpenOffice.org code conventions. for an expaination of variable naming schemes etc.
- Some Notes on How to Debug LibreOffice
Assertions and Logging
To assert invariants of the code (that can only be violated if there are programming errors) use standard C/C++
assert. Production builds define
--enable-dbgutil do not. Do not follow an
assert with code intended to mitigate the consequences of the detected programming error in production builds.
To log warnings about unusual events (that the code nevertheless needs to handle in some way, like malformed input or I/O failures), use the
SAL_WARN_IF macros from
sal/log.hxx. It is generally better to report a detected problem up the call stack than to silence it locally. That is, a
SAL_WARN is likely followed by a
throw, and code should not catch and swallow exceptions that it cannot meaningfully handle.
To log other information useful for debugging, use the
For temporary debug output, use the
SAL_DEBUG macro. Commit hooks will prevent accidental committing of it.
SAL_INFO macros are inactive in a production build;
--enable-dbgutil activates them. Which logging calls actually produce output is then further controlled by the
SAL_LOG environment variable. See the documentation in
sal/log.hxx for further details.
The functionality offered by
tools/debug.hxx is obsoleted by
Further developer hints
- use http://opengrok.libreoffice.org/xref/core/ !
- Release Plan
- Some Notes on String Classes used in the source code
- Some Notes on Development/Sal_Types
- How to deal with dictionaries
- How to merge a new milestone from OOo
- Hints when developing more complex features
- Unit tests
- LCOV Code Coverage reports
- Clang static source code analysis
- Cppcheck static code analyzer
- Source Code Documentation
- Writing source code documentation
- Vim tips & tricks
- Build System
- FOSDEM 2012 slides of talks