Preparing a patch for OpenOffice.org

 

 

Javier SOLA - www.khmeros.info - Last edited 11/15/2004 - Top

 

This file contains work in progress.

It is only published for public review leading to its improvement, change... or utter destruction, if necessary.

This documenthas not yet been checked nor approved by OpenOffice.org, so it might also contain errors.

Any advice is welcome, be it on form, language, structure or contents.

The contents of this pages might (and probably will) change often without warning

 

 

A patch is a proposed modification to a file that already exists in the system. The traditional way of sending a patch to OpenOffice is not to send a new copy of the file, after you modify it, but to send a file that shows the differences between the old file (before you modified it) and the one that you have modified.

 

To prepare a patch that you want to have integrated in the source of OpenOffice, you first need to have the version of the file that corresponds to the version of the program that you are localizing it for.

 

Which brings us to talk about "branches" and "tags". When OpenOffice reaches a major version (say 2.0), it "branches", meaning that two copies of the source are made: 

  1. One of them to continue development towards the next major version (say 3.0) in which at some point many changes will be made until it becomes stable again for 2.0;

  2. The second copy will not receive major improvements, it will only be modified to fix bugs bus for the original version (reaching versions 2.0.1, 2.1.1, 2.1.2, etc...) while the next major version is being developed in the other branch.

Each branch has a major name which is included in all the "tags" of files in that branch. For OpenOffice 1.x, it was srx645, for OpenOffice 2.0 it is rsc680. Each time that a file is modified, or that it is used in a new build, it is assigned a new tag. A file , without being modified, might have a lot of "tags". For example, if a file has tag src680_m45, it means that it was used for the src680_m45 build. If that file was not modified for the next build, it will also have tag src680_m45.

 

All this comes to say that you need to figure out which branch of the program you want to have modified. If the problem that you have detected is in version 2.0, you cannot fix the bug or make the change for version 2.0 (because 2.0 is already closed and out). You either do it for a bug fixing version (2.0.1 or 2.1, whatever the next version will be) or for a major new version. So, once again, you need to figure out which branch you want to affect, and find the last version of the file in that branch. This is not too difficult to do if you know were to look.

 

If you don't know the major name of the branch you are looking for, ask in the list.

 

You can look at the files of OpenOffice from the web (webCVS). In OpenOffice this is a little tricky, because you need to know to which project the file belongs within OpenOffice, go to the project's webpage, and there click on "version control", and then find the file in the tree.

 

Let us say as an example that the file that you want to modify is tools/source/intntl/isolang.cxx (which belongs at this time to the utilities project). You need to go to the page of the Utilities project, click on "Version control", then click on Tools, in the next page on Source, on intntl in the next, and finally click on isolang,cxx. Right now, to make it easier we give you exactly the direct URL of the page:

http://util.openoffice.org/source/browse/util/tools/source/intntl/isolang.cxx

This page, at some point in history (when this document was made), looked like this:

 

 

 

If you go into this page, you will see - one after the other - all the revisions that the file has gone through (first at the bottom, last at the top), and all the tags that relate to each revision. The revision of the file that you are looking for is the first one that you find (higher in the page) that has a tag that includes the name of the branch that you are looking for.

 

You need to click on "view" for that revision, so that you will get a new page with some comments and then the contents of the file. Select and copy the content of the file in the browser and copy it to an empty utf-8 file (and save it with the same name).

 

Of course, you can always use CVS directly (not webCVS) to get the right version of the file, if you now the tag, but the tricky part is to know the exact tag of what you are looking for, and using webCVS makes it easy to find.

 

Now that you have the file that you want to modify, keep a copy of the original (say old_isolang.cxx) and modify what ever you need in your copy. Test it is needed be. Once you are happy with it, and want to submit the changes to OpenOffice, you need to do a "diff" between the old file and the new one.

 

If you are working with Unix or Linux, all you need to do is to use the "diff" command in the following way:

 

diff -u [old_file] [new_file] > [patch_file]

 

You might want to give to the patch file the same name of the file, but adding to it a ".diff" or a ".patch" extension, so that everybody knows what it contains.

 

Windows has the same function in the command prompt, so you can do the same thing on Windows, but you do need to make sure that the result is a UTF-8 file with no BOM mark and with Unix-like endings.

 

You probably want to look at the file that you just created with the diff command. It should list each line that you have added, erased or changed from the original file. You might find there changes that you did not want to make and that are not important (such as one of the files have one more blank line at the end) or one more space in some line. It is nice for whomever has to review your patch, to make sure that those things are the same as the original, so that the reviewer does not have to pay attention to them. Please modify your file to be the same as the original in those unimportant things, and do a new -cleaner- diff.

 

If you are used to CVS, you follow a slightly different process: you can uncheck the file from CVS, make your modifications and the do the diff using also CVS, with the command:

 

cvs diff -u  

 

This assures that the diff is done against the last version, in case the file had changed from the time you downloaded it.

 

As mentioned above, the patch file needs to follow unix-like file conventions. It must be in UTF-8 format, without a BOM mark (a mark at the beginning of the file which indicates that it is in UTF format), and the line-endings inside the file must be unix-style (0x0A character), and not DOS/Windows style (0x0D + 0x0A characters). If you are working on Windows and you wish to make sure that your file has Unix-like endings, you can use the NoDosNoBOM utility. It can be used with two arguments, if you do not want the original file to be modified, as in:

 

NoDosNoBOM [OriginalFile] [DestinationFile]

 

or as

 

NoDosNoBOM [File]

 

if you want to make the changes in the file itself.

 

When you use programs that modify your files, you should always make a security copy of your files before you start

 

As a hint, pure ASCII text files are also UTF-8 files (the formats are compatible).