- 1 How to get involved
- 2 Getting your first build done
- 3 Using Git for LibreOffice development
- 3.1 ./g
- 3.2 Managing git branches
- 3.3 Reorder, squash and in general tweak your local history: git rebase -i
- 3.4 Getting and using commit access
- 4 General Programming Guidelines
- 5 Working on specific sections of libreoffice
- 6 Debugging
- 7 Development / Hacking Notes
- 8 Release Plan
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. For an overview of the complexity of LibreOffice, see the Code Overview page to help you get a grasp what the directories and repositories are for.
There is also a list of Frequently Asked Questions.
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. You can also find a generic list of Easy Hacks in the bugtracker: Easy Hacks in the Bugtracker.
For a general introduction, see Michael Meeks slides for the Easy Hacks Talk at FOSDEM 2012.
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 developer mailing list, let us assume you started with a unmodified master branch. The steps are as follows:
- Hack the code to your hearts content (if you plan something bigger, consider using feature branches)
- Commit your changes locally to git. The first option adds all modified file, while the second option allows you to select which files become of the commit:
git commit -a ... or ... git add <file1> <file2> ... git commit
When you type a commit message, use 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.
- 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 follow these instructions to go back to a pristine vanilla branch.
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.
Bugzilla-integration with commit-messages
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.
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.
Developer mailing list - how to use
Please read this page.
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/ . The rest of this article will assume a basic working knowledge of Git.
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.
The core repository contains a little utility named g, located in ./g. it is a little script that allow you to run the same git command on core and all the repository you have in clone/.
When manipulating branches (creating them, switching them etc... it is usually a good thing to use ./g to keep all repository in the same state)
Most commands that you would type as git xxxx, can be typed as ./g xxxx which means 'run git xxxx on each repository contained in ./clone/'.
Managing git branches
There is a page dedicated to the branches we have in our git, please have a look at the Development/Branches.
Check the current branches
To see which branch your repositories currently are on, issue:
~/loroot $ ./g branch
This lists the local branch for each repository and put a '*' in front of the one currently active. Every repository should report the same branch as active.
Adding -r after the branch command will show you the branches that are available on the remote repositores (e.g. the list of available feature branches).
Switch to a feature branch
Let's create a new feature branch 'feature/slicebread' on all git repositories based on origin/master, which allows you to safely develop a new feature:
~/loroot $ ./g checkout -b feature/slicebread origin/master
If you display again the active branch, all repositories should report 'feature/slicebread'.
If you want to switch to an existing feature branch, rather than creating a new one, do:
~/loroot $ ./g -f checkout -b feature/slicebread origin/feature/slicebread
This will create a local branch 'feature/slicebread' which tracks the remote branch feature/slicebread. The -f forces bin/g to go through all repositories without aborting, even if some repositories don't have the branch.
Going back: If you ever want to go back to master and delete your local branch, make sure you don't have any uncommitted changes in your repositories, then first go back to master, and then delete your local branchfeature/slicebread.
~/loroot $ ./g checkout master ~/loroot $ ./g -f branch -D feature/slicebread
Hack and commit on a feature branch
Now you can hack and compile as you wish. Do not be shy about committing your work. These commits are purely local and will not be visible until you publish them. You can always re-organize or fuse some commit later if you want to present a cleaner history. Each commit should contain a set of changes that are related to each other and be described clearly in the commit-log message. The first line of the commit-log message must be a concise (80 chars or less) summary of the change, then skip a line and enter a more detailed description as-needed.
Now you have implemented your new feature or you have made some progress and want to get some feedback.
First, since the master branch has probably changed since you branched-out your feature branch, you should rebase your changes, so that they apply to the most current master's HEAD.
To rebase, you need to make sure that you have committed everything that matters and clean-up your repository so that there are no changes 'pending'. Then return to the master branch with:
~/loroot $ ./g checkout master
Refresh your master branch
~/loroot $ ./g pull -r
Go back to your feature branch
~/loroot $ ./g checkout feature/slicebread
~/loroot $ ./g rebase origin/master
If there are conflicts you need to resolve them manually and continue rebasing until you're done.
Now, it's time to publish. There are two cases.
If you do not have a set of git repositories to push these changes to, then you want to prepare a set of patches to be able to post them on the Dev-List for review.
~/loroot $ ./g format-patch --suffix=-@REPO@.patch --output-dir=<where_you_want> master..HEAD
This will generate a file per commit suffiexed by the repo name, in the directory you specified. You can then attach them to an email to the mailing list.
If you have the ability to push to a set of git repository, then
~/loroot $ ./g push origin feature/slicebread
There are plenty of excellent tutorials, books and even videos on how to use git. You are strongly encouraged to look into them. The LibreOffice Development Environment has 20 git repositories that are logically one but need to be cared for individually (hence the g and ga script).
Hack and commit on a stable branch
Stable branches are created from master or another stable branch to stabilize the code base for the release and further maintenance updates. There are some rules during the beta phase:
- allowed are any changes in translations
- allowed are any bug fixes
- allowed are late features that are approved by Steering Committee
There are more strict rules during the release candidate phase:
- allowed are safe fixes that are reviewed by another person, see below
- allowed are changes in translations; it is recommended to ask for review on the native l10n mailing list
Please, do not commit the fixes directly during the RC phase. Instead, please, ask another developer for review on the email@example.com mailing list, personal mail, on IRC or via the related bug entry. The fix should be committed by the reviewer using:
git commit -s --author='Author name <firstname.lastname@example.org>'
What to do when git pull -r does not want to operate
It is usually due to local changes in your repository. You can either get rid of them, using:
git checkout -f ; git pull -r
or stash them temporarily, and get them back again after the git pull -r:
git stash ; git pull -r ; git stash pop
Reset your modified repo to a pristine "vanilla" repository
~/loroot $ bin/g reset --hard origin/master
will discard all your local changes (whether committed or not) and reset the current branch that you are on to the one on the remote repository.
Reorder, squash and in general tweak your local history: git rebase -i
git rebase -i is a powerful tool that allow you to 'rewrite' your local history. This should only be done on commits that have not been pushed yet!!!
Let's say you are on master and the last 3 commits are A,B,C=HEAD but C is actually a correction of the commit A that you missed before committing B. So what you would want to do is to merge A nd C together and end-up with A',B as history
To do that you can
git branch safehead HEAD
This is just in case something goes very wrong and you want to just undo everything and go back to the initial sate
git rebase -i HEAD~3
This should bring, in your favorite editor something like this: (this are listed from the oldest to the newsest, the reverse order than normally in git log, so C is the last of the list)
pick 726fe9c enable localization of extension descriptions in mysqlc pick 9ab6ecf fix en-US only build pick a18bfb0 Revert "enable localization of extension descriptions in sdext" # Rebase 1846533..a18bfb0 onto 1846533 # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup = like "squash", but discard this commit's log message # x <cmd>, exec <cmd> = Run a shell command <cmd>, and stop if it fails # # If you remove a line here THAT COMMIT WILL BE LOST. # However, if you remove everything, the rebase will be aborted. #
edit it, moving commit C one-up and changing its action to squash:
pick 726fe9c enable localization of extension descriptions in mysqlc squash a18bfb0 Revert "enable localization of extension descriptions in sdext" pick 9ab6ecf fix en-US only build
the save and exit the editor.
If everything went nicely you should be on master with your HEAD on B and A+C fusionned just before B. If things went wrong and you are lost:
git rebase --abort
if things are not reverted to the way they should (compounded wrongness :-) you can
git reset --hard safehead
to pretend nothing ever happened :-)
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
General Programming Guidelines
sal_Bool should be used only when it comes to UNO, and bool is preferred otherwise.
The OpenOffice.org code conventions. For variable naming schemes etc.
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
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
Working on specific sections of libreoffice
As currently implemented, there are two main configure.in files, one in the top-level build directory, and one in the libreoffice sub-directory. Any important changes should be made to both, as the top-level one is slated for removal once all the patch-sets currently in the system have been merged into the main code base.
The default arguments into the build system are currently in <loroot>/build/distro-configs.
Current configure options of the sub-level configure.in and also which options are top-level present only.
- Some Notes on How to Debug LibreOffice
Development / Hacking Notes
- Some Notes on String Classes used in the source code
- Some Notes on Development/Sal_Types
- How to merge a new milestone from OOo
- Hints when developing more complex features
- Unit tests
- Source Code Documentation
- Writing source code documentation
- Vim tips & tricks
- FOSDEM 2012 slides of talks