The Document Foundation Wiki
 

Development/Patch Handling Guidelines

From The Document Foundation Wiki

Jump to: navigation, search

Contents

Preamble

The purpose of this page is to provide a detailed guideline for submitting patches and integrating submitted patches in order to make this process efficient and scalable. Since the number of patches submitted to this project has started to grow dramatically, we need to put some sort of guideline to make the patch integration process scalable. Speedy and timely handling of patches is the heart and soul of LibreOffice project that should never be compromised; however, it's not ideal if the core developers end up spending most of their time reviewing patches instead of fixing bugs and implementing features that are assigned to them. This guideline hopefully provides a good middle-ground between the need for speedy patch integration and the need for on-going core development.

General workflow

  1. Patches are submitted to the developer mailing list (libreoffice@lists.freedesktop.org) with [PATCH] in the subject line, to indicate that the post includes a patch.
  2. Developers with commit access to the public repository regularly scan the mailing list looking for those with [PATCH] in the subject. When a patch is found, either that developer reviews the patch, or ask another developer who can review this patch in case the patch is non-trivial and needs someone with more expertise in that area to review.
  3. When the review is OK, the committer commits the patch locally, with --author="Name of the submitter <email address>" option, and push it to the remote repository. When the review concludes that the patch needs more work, the reviewer replies to the thread indicating what needs to be fixed, or the reviewer puts the fix in on behalf of the submitter if the fix is trivial.
  4. When the patch is pushed to the remote branch, reply to the thread with [PUSHED] in the subject line, indicating that the patch has been reviewed and pushed.

How to submit a patch

Example first

Let's say you have modified a file in sw (it means in Writer):

cd sw
# add the file to commit (alternatively you can do git commit -a)
git add the/file/you/have/modified.cxx
git commit
# check what you have committed
git log -p
# if all looks good (according to what you can read on this page), generate the patch
git format-patch HEAD~
# it will write you the name of the result, so just send it
# to the libreoffice@lists.freedesktop.org mailing list :-)

Generate patch via git format-patch

Our preferred patch format is one generated by git format-patch command. This format is most convenient in that it contains commit message and patch author information as well as the code change itself. It can also handle changes in binary files which the traditional patch format generated by the diff command cannot.

Review your own patch before submitting to the mailing list.

Especially look out for

Keep your patch under a reasonable size.

A giant, mega patch that touches 100's of files would require the reviewer to spend a whole day (or two) just to review the patch. So, if you can divide that into multiple smaller chunks, please do so.

Give each commit a distinct purpose.

For instance, a commit that translates German comments, removes commented out code, and fixes a bug should be separated into three distinct commits, one that does the translation, one that removes commented out code, and one that fixes a bug. Git allows you to make many local commits before pushing to the remote repo or having them committed by a committer. Let's take advantage of this and avoid making giant commits that do many things in one go.

Keep German comment translation separate

This is related to the point above. If you translate German comments into English, please keep that in a separate commit, and avoid doing other changes in the same commit. People able to review German translations and people able to review code cleanups are not necessarily the same, and combining both kinds of change in one patch may delay the patch to be processed.

Even if you do only German comment translations, please do your git commit after having run ./autogen.sh (with any options) and ./g -z, even if you do not build LibreOffice. This sets up git commit hooks which will automatically check your commits for various common policy violations (such as trailing whitespace, tabs in indentation, ...).

Build the module before submitting the patch.

If you are comfortable building LibreOffice, please do check to make sure your change doesn't break the build at least on the platform that you work on. You don't necessarily have to do this when the patch only translates German comments or remove commented out code (though we still prefer that you do), but in all other cases you are encouraged to ensure buildability of the module you modify.

Send patches as attachments or use git send-email.

You can either send patches as attachments to an email, or by the git send-email command. If you have more than one patch to submit, you can attach them to a single email if they are related; otherwise please send them as separate discussion threads. When sending multiple related patches in one step via git send-email, we prefer that you use the --thread --no-chain-reply-to options which sends the first patch as a new discussion thread, and all the rest of them as direct reply to the first one.

Whatever you do, Don't paste the patch content into mail body. Doing that would break long lines into multiple lines which would make it painful for the committer to commit the patch.

Be patient while waiting for review.

While many core developers are paid to work on this project full-time or nearly so, our increasing number of committers and patch reviewers do this in their precious spare time. So, please be patient when your patch does not get reviewed right away.

Note for patch integrators

Build the module after applying the patch.

After applying each patch, please make sure the module to which the patch has been applied builds. This applies to all patches, even those that translate German comments and remove commented out code.

Apply patch via git am or git apply.

We encourage our patch submitters to submit patches generated by git format-patch. You can apply these patches directly by running git am command, which conveniently applies the commit message and the author information as well as the code change in one go.

Occasionally, patch submitters submit patches generated by git diff. These patches can be applied via git apply command, followed by git commit to commit the change to the repo. When you handle patches of this kind, you need to manually specify the commit message and the author information when running git commit. Use the --author="Foo Hacker <foo.hacker@somedomain.com>" option to specify the patch author when committing these patches.

Patches sent by git send-email command sometimes don't show up as attachments but as the message body. When you encounter this, simply save the email as File - Save As (or equivalent in your email client) to save the raw email content as file, then run git am on it.

Sometimes a patch generated by git format-patch and sent as an attachment prepends a ">" on the first line of the patch. When you run git am on such a patch, you get

 Patch format detection failed.

When you experience this, check the first character of the patch to see if it looks like this

 >From 1c3fd02c580eb09eaa00d191a1dd2fe6dcc4e73d Mon Sep 17 00:00:00 2001

and if so, try removing the first ">" character, save the patch, and run git am again to see if it succeeds.

Reply to the thread with [PUSHED] tag

Be sure to reply to the thread where the patch is submitted with [PUSHED] in the subject line when you pushed the patch to the remote repo. The [PUSHED] tag should be near the front to ensure that it be visible even when the subject line is truncated. This helps us be aware of which patches have been integrated and which still need to be reviewed. To make this work, it's important that you reply to the thread where the patch is submitted such that when thread view is turned on in the email client it would show up on that thread tree. Note that some email clients don't put In-Reply-To header when replying to an email, which would break proper threading. Please check with your email client to make sure that it supports In-Reply-To header properly.

Personal tools
Namespaces
Variants
Actions
Wiki
Navigation
Toolbox
donate