How to contribute code or translations

When you have developed something, you might want to see your changes included in ooo-build. To be able to do so, you need to have a clone of the ooo-build repository - please check the GettingIt pages - but you probably already have that.

Then just commit your changes to your local repository, and either mail the changes to ooo-build@lists.freedesktop.org if you don't have the write access to the repository, or push them if you have it.

Committing the changes

With git, committing happens locally; you have to push your commits later so that they appear in the remote repository.

You probably want to use any of the following forms of committing

# commit all the changed or removed files
git commit -a
# commit the specified files
git commit file1 file2 file3 ... fileN
# first mark the files that you want to commit, then commit them
git add file1 file2 file3 ... fileN
git commit

Of course, there's also the usual:

git rm file1 file2 # remove file
git mv source dest # move file
git commit         # commit the removes/moves

Note that there is no git cp - git detects the history for file moves/copies after the fact, so you should be OK with only using

cp file1 file2
git add file2
git commit

The commit logs should have the following form:

First line roughly describing the change.

Leave one empty line, and then follow with more detailed description
what and why you changed.  It is really important to provide a good
description on the first line, because some of the git tools (like
gitk, git log --pretty=oneline, git rebase --interactive, etc.) show
just the first line.  Also we don't have a ChangeLog any more, so
git log is now your source of the information about the changes.

Please do not forget to mention the bugzilla numbers, like i#12345 or
bnc#234567.

* file1: Did this and that.
* file2: And something else here.

You can leave out the '* file: Did this and that' part if the general description is descriptive enough, or leave out the general description, if you store all the info in '* file: XYZ' part, but please never ever forget to provide a good first line.

The commit hooks that get installed when you do ./autogen.sh should help you to create good commit messages.

Mailing the changes

If you do not have the write permissions [yet ;-)], just develop like if you had one & commit the stuff to your local repository. Then instead of 'git push' please mail the results of

# if you are on the branch 'master', and want to mail the commits done there
git format-patch origin/master
# more verbose version, when you want to eg. mail changes committed on branch ooo-build-3-1
git format-patch origin/ooo-build-3-1..ooo-build-3-1

to the dev@lists.go-oo.org mailing list. One of the developers with the write access will review, and push them for you using

# apply the patches from the mailing list
git am 0001-the-first.patch 0002-the-second.patch 0003-the-third.patch
# check them briefly
git log
# check them better
git log -p
# push
git push

Pushing the changes

If you have write permissions to the remote repository, and want to publish your changes, push them to the repository using

git push

When it fails because somebody else has pushed something, update your repository using

git pull -r

as already described above. Again, don't forget the -r!

Note: If you used just 'git pull' instead of 'git pull -r' accidentally, you can still fix that by re-running git pull -r. There is also a hook that warns about the plain 'git pull' usage, and instructs you what to do.

Note2: You might get warnings during git push when you have multiple branches to push in your repository (which happens when you eg. did not delete the master branch though it is recommended in 'Getting a particular branch'). These are just warnings, but if do not want to get them, use the full form of git push:

# let's push just the branch 'ooo-build-3-0-1'
git push origin ooo-build-3-0-1

What if I committed something wrong

If you did not push it yet, all is fine. Just use

git rebase -i origin/master
# [this supposes you are in the 'master' branch; for ooo-build-3-0-1
# you would use origin/ooo-build-3-0-1]

and edit the history. The use of origin/master as the starting commit decreases the probability that you'll do something wrong.

'git rebase -i' presents you with a list of the commits and a small help; you can let the commit as it is, move it up/down, remove it, squash it together with the previous commit(s), or edit it.

After you save the list, each time there is a conflict, or when rebase finds a commit to edit, you get a shell, do your changes, git add the.txt changed.txt files.txt, and git rebase --continue. After few iterations, and with a bit of luck, all will be as good as you wanted.

However - if you pushed your changes already, don't you try to rebase them! You have to commit the fixes and push them as completely new stuff.

Introducing a change in more branches

To get commits from other branches, please use

git cherry-pick <commit-id>

It will take the changes introduced in , and commit them in the current branch.

We may allow full merges from other branches in the future, but so far we do not consider it safe on the branches automatically converted from the SVN.

Managing translations (info for translators)

ooo-build includes two different .po files:

• ooo-build/po/.po - used for the desktop menu entries in ooo-build/desktop/*; they are processed the GNOME way using the intltools and are applied directly during the build
• ooo-build/po/ooo-build-.po - used for new or modified strings from ooo-build patches; they are based on ooo-build/po/ooo-build.pot file; they are not used directly during build but the ooo-build-.sdf files are used instead; the sdf files can be regenerated by the command: make update-sdf. Translators need not take care of .pot or .sdf files. They are regenerated by ooo-build developers when necessary (before release). Any new or updated .po file can be either pushed directly to ooo-build (in case you have the fd.o account) or mailed to the mailing list. See Mailing the changes section on how to do it.

See also ooo-build/po/README.

Managing patches

ooo-build itself is in git - but as a set of patches, not the patched OOo sources themselves. Working with patches is unfortunately not too straightforward and needs some training.

The patches are located in the patches/ subdirectory, like patches/dev300/. Additionally, there is a so-called apply-file, that defines which patches should be applied, and in what order.

Patch name

The patches in patches/*/ should follow these conventions:

• They are required to have a .diff suffix (not '.patch')
• When there is more patches to implement one feature, we suggest a pattern like <theme>-short-fix-description.diff, where the is eg. warnigns, unittesting, speed, etc.
• We suggest a pattern like <module>-short-fix-description.diff when the patch modifies only one source , like vcl, svx, sd
• A name like cws-<name>.diff should be used for CWS backports
• short-fix-description.diff is enough otherwise

Patch format

The patches are to be applied in the top source directory (eg. build/ooo320-m12) with -P0, so the content of the patch should look like the following:

--- jvmfwk/plugins/sunmajor/pluginlib/gnujre.cxx.old    2007-08-10 17:32:26.0000
+++ jvmfwk/plugins/sunmajor/pluginlib/gnujre.cxx        2007-08-16 22:40:42.0000
@@ -78,6 +78,7 @@ char const* const* GnuInfo::getJavaExePa 
...

Patch location

Most patches are located in patches/dev300, which follows the up-stream notion of Master Workspace (MWS) - dev300 means the main development branch. Bigger groups of patches might have their own thematic directory though. For example:

patches/dev300/sc-save-split-view.diff
patches/dev300/warning-return-values-filter.diff

patches/vba/vba-something-cxx.diff
patches/vba/vba-something-hxx.diff

The apply file

ooo-build allows to sort the patches into groups and apply them conditionaly by distributions. Therefore, each patch has to be mentioned in the right section in the apply file. This file is usually located in the MWS-specific directory, these days mostly patches/dev300/apply. The patch entry might look like:

[ CalcFixes ]
# Support Hungarian localized keywords for CELL and INFO functions.
sc-celltrans-hungarian-keywords.diff, i#80299, kohei
# Fix saving split-view information on 64-bit platforms.
sc-save-split-view.diff, n#235131, i#81936, jonp

The form is name-of-the-patch.diff, , . Please do not forget to mention this information, it is necessary for further tracking.

NB. the patches are applied in the order in which they are listed in the apply file. If there are conflicts between the patches, it might be necessary to split a section, like:

[ Fixes ]
# make unzip command not ask when overwriting files
unzip-command.diff, i#81087, fridrich

[ CalcFixes ]
#fix import filter for userforms with calc specific data ( rowsource ) 
svx-filter-userform-rowsource.diff, i#73753

[ Fixes ]
# edit fields text displaying
svx-sdrobjeditview-update-edit-area.diff, n#305205, rodo

Managing patches using git

You can use git to do same of the heavy lifting for you, by adding a local git tracking of the patched OOo sources, like:

make patch.apply
cd build/oooABC-mXY
git init
../../bin/create-gitignores.sh
# if you want to track just the 'sc' project
git add sc
# or instead track everything
git add .
git commit -m "initial"

Creating a new patch

Now you can create a new patch like this:

cd build/oooABC-mXY
# create a branch for the development
git checkout -b tempbranch
# modify the file, eg sc/blah/bleh.cxx
# and commit it
git add sc/blah/bleh.cxx
git commit
# edit something else, commit, etc.
# create the patch
git diff --no-prefix master tempbranch > ../../patches/dev300/blah.diff
# now switch back to master
git checkout master
# and add the patch to ../../patches/dev300/apply (as described below)

Update an existing patch

To update an existing patch, you'll probably want to do something like this:

# create a temporary branch
cd build/oooABC-mXY
git checkout -b tempbranch
# unapply the patch
patch -p0 -R < ../../patches/dev300/blah.diff
# commit the revert
git commit -am revert
# apply the patch again to be able to edit it
patch -p0 < ../../patches/dev300/blah.diff
# edit it, commit the changes
# when you are happy, find the commit id of the 'revert' commit
git log
# generate the patch
git diff --no-prefix id-of-the-revert-commit > ../../patches/dev300/blah.diff
# switch back to master
git checkout master

To remove the git tracking :

rm -rf .git

You can also think of more fancy use of git, like having a master branch for applying the patches, and other branches to track history of development you are doing, or use it to actually edit existing patches, to merge patches, etc.

Some people prefer stacked git (stg) over plain git when juggling with patches, after the initial git init; git add .; git commit -a do a stg init - and read the nice manual page.