Translations of this page: http://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Flag_of_Spain.svg/22px-Flag_of_Spain.svg.pngEspañol


WineHQ Patch Submission Guidelines

In order to review code better and use established lines of communication, the Wine project accepts code in the form of patch files (instead of pushing directly to the main git repository). The process may seem a little complicated at first, but it will probably become very natural after just one or two submissions.

Can I Submit Patches?

Not everyone can contribute code to Wine, primarily because doing so would violate the CleanRoomGuidelines. If you have studied the Microsoft Windows source code, even if you aren't under a non-disclosure agreement, your patches probably won't be accepted. This is to ensure that the Wine project does not violate any copyrights belonging to Microsoft. Some more notes related to this can be found in the DeveloperFAQ.

Check Your Git Setup

Because many developers use their mail clients to process patch submissions, it is important to make sure the author and email settings for your git repo are configured correctly.

git config --global user.name "Your Name"
git config --global user.email "me@example.com"

GitWine has more details, but the key point is to use your real name. This isn't just for developers to show a stronger commitment and establish trust, but also helps discourage irresponsible programmers from submitting unacceptable code (such as dissassembled Microsoft components).

Also, if you decide to attach your patches instead of inlining them in your email, many mail clients will automatically change the mime-type of git's default .diff output. The workaround for this is to set git to output patch files as .txt files.

git config --global format.suffix .txt

Finally, there's always a chance that someone has recently changed the same code you are working on. To make sure your code hasn't been superseded, be sure to update your git repo before generating your patch files.

git fetch
git rebase origin

If you prefer to manage your work in separate GitBranches, remember that the above command will only update your current branch and all of your branches need to be up-to-date. Keeping your "master" branch in sync with WineHQ's repository and creating branches (and rebasing them on "master") for your own changes might be a good idea. Again, the GitWine page goes into much more detail on using git to manage your work.

Making Your Changes

Code Guidelines

If you are making changes to the Wine program itself, there are some basic rules your code should follow to pass review. In order to make your changes as easy to check as possible, try to keep them small, clear, but atomic:

  • Follow the style of surrounding code as much as possible, except when it is completely impractical to do so
  • Use a consistent style in your own changes (e.g. don't write foo* bar in one place and foo *bar in another)

  • Convert tabs to spaces and remove trailing whitespace from your changes, but don't change whitespace in other lines
  • Avoid very long lines (100 chars is a safe max width, but it's not a hard limit)

  • Only include closely related changes in one patch
  • If you've written a fix and new ConformanceTests for an issue, include them in the same patch

  • Try to limit a patch to changing a single file or component unless that would break something somewhere else

These rules also help make TestingRegressions easier, and prevent new bugs from slipping through.

There are other coding rules that affect the quality of Wine itself more than your patch files. To read more about these guidelines, see the Coding Practice chapter of the Wine Developer's guide and the coding conventions section of Developers-Hints.

You can also look at the wine-patches and wine-cvs mailing list archives to see all submitted patches and the ones that actually get committed. Try to imitate the style of the successful patches.

Related parts of the Wine project, such as the website, may have slightly looser requirements on patches, but it is still important to keep patches clear and simple, bundle related changes together, and not break anything.

Testing for Problems

Be sure to run the conformance tests on an unchanged branch of Wine (or before you make any changes) to see where your system is OK (The MakeTestFailures page has a few notes on common problems). Then run the tests again after you make your changes to verify that they don't break anything new. If you've added or modified any of the conformance tests, be sure to check that they work properly by using the make crosstest command, then submitting the resulting executable to WineTestBot.

Also, make note of any significant compiler warnings that come up when building your modified version of Wine and fix the underlying cause before submitting your patch. Finally, if you've changed any part of the build system, make sure that it works on both GNU make and pmake (used by Mac OS X, BSD, and Solaris).

Generating and Submitting Patches

Creating Patch Files

GitWine includes more details about the different ways to create and send patch files. Once you've committed some changes to your git repo, you have two main choices. If you have git configured correctly and access to an IMAP service, you can mail your patches directly from the command line. Simply pipe the output of git format-patch to the git imap-send command:

git format-patch --stdout --keep-subject --attach origin | git imap-send

That should upload your patches into your IMAP drafts folder, and allow you to check and send them. In Mozilla Thunderbird, that is as simple as clicking "Edit Draft..." then "Send" if the mail headers in the git config file are set correctly.

If you can't use IMAP, the following command will generate a series of patch files (one for each commit beyond the origin branch):

git format-patch --keep-subject origin

This command outputs the files in the current working directory, but you can specify an output directory by using the -o flag:

git format-patch --keep-subject -o outdir origin

You can now review and mail these patches manually (please remember to use the .txt extension as it makes the patches easier to review.)

Quality Check

Whether you do so in the drafts folder of your mail client or by reading the files in a directory, it never hurts to check through your patches one last time:

  • Look at each line of the patch, make sure there are no unintentional or unrelated changes
  • Remember not to actually edit the patch file itself. If you find errors, change the code and generate a new patch file
  • Did your fix pass all related tests? If it wasn't covered by a test, have you written a test of your own?

Writing the Email

There are a few things to look out for when mailing in your patch. First, be sure you address the patch to the wine-patches mailing list, wine-patches@winehq.org, and remember you need to be subscribed to the mailing list in order for your submission to get past the spam filter. Remember that you will only be including one patch with each email, so if you have multiple patches, you will need a different email for each one.

The Subject Line

A coding system is used in the subject line in order to sort submissions:

  • If you are sending multiple patches that depend on each other, the subject line should begin with a fraction enclosed in square brackets, giving the patch's order and the total number of patches in the set:

[1/3] This is the first patch
[2/3] This patch depends on the first one
[3/3] This patch depends on the others

If you're using git format-patch, you might want to set format.subjectprefix to an empty string in your git configuration file, to avoid getting the PATCH word in all your patch titles (i.e. [PATCH x/y]).

  • Next, if you are submitting a patch for something other than Wine itself (such as the website or documentation), include the project code in square brackets:

[website] Added ... translation
[bugzilla] Fix ...
[docs] Updated ...
[appdb] Add Feature ...
[tools] Fix ...
[fontforge] Fix ...
  • If you are fixing a specific component or part, write the component's name followed by a colon:

[1/2] msvcrt: First change...
[2/2] msvcrt: Second change...
wined3d: Separate change...
  • Now add the brief description you would like to appear in the git log:

[docs] winedev: Improved description of build system
  • Finally, if your submission somehow fell through the cracks and you're trying to send a patch again without changes, include "(resend)" after the description. If the patch had errors and you've changed it before resubmitting, include which try you're on in parentheses:

user32: This patch just got lost somehow (resend)
ntdll: This patch was wrong the first time (try 2)
comctl32: This patch has failed twice (try 3)

The Submission Body

/!\ Know your mail client. Be careful that the patch isn't corrupted by the mail-client's line-wrapping. Some mailers let you enclose the patch in the body of the mail without any problems, but Mozilla isn't one of those (at least it didn't used to be). If you use a mail client that does inappropriate line-wrapping, make sure to attach your patch as a single, plain .txt file. Also, to be safe, try to always send your emails as plain-text, not html or rich-text.

At the top of your email, you should include a short note explaining what the patch accomplishes. It should mention what operating systems you ran the tests on. If it is an updated version of a patch that has failed to go through, describe the changes you made, and reply to any feedback from other developers. Also, if your patch fixes a bug, be sure to mention the bug number, but do so here in the explanation, not the subject line.

Right below this, you will need to include a single diff of the files that you've changed in that patch. Do not include diffs for files that are automatically generated or updated and not tracked by Git, unless they absolutely have to be edited manually. Examples include Makefiles, build scripts, headers generated from spec files, and po translation files. To find the diff, you will probably just need to copy and paste it from the beginning of your patch file, which looks something like this (be sure to include the three dashes):

---
 path/to/filea.c |    9 ++-------
 path/to/fileb.c |    9 ++-------
 2 files changed, 4 insertions(+), 14 deletions(-)

If you wish and your mail client won't cause any problems, you may include the rest of your patch file in the body of the email too. However, attaching the patch as a .txt file should work with all mail clients, and may be neater for large patches.

Managing Your Submission

After you've submitted you're patch, you should watch the wine-devel mailing list for feedback on your patch (although replies should normally be CCed to you, sometimes people may forget). If your patch does get some feedback or a critique, carefully think about what they say and fix your patch before resubmitting. If others point out a few flaws in your patch, it's safe to assume that they missed some too so try to check the whole patch and fix other flaws before resending.

Also be sure to watch the patch status page to see how far it has gone. The maintainer usually commits twenty or so patches all at once at the end of the day (European time). If your patch had no negative feedback, the maintainer will have a look at it as soon as he can. Patches from those who have successfully committed patches before, and who are known to test their work thoroughly, are likely to be committed quickly. Patches from new developers require more scrutiny and the maintainer will probably not get to them immediately, but this does not mean your patch has been forgotten.

If your patch disappears from http://source.winehq.org/patches/ without being committed and without feedback, improving it (perhaps by adding more tests) and resending it may help, or you can ask on the IRC channel or developers' mailing list for suggestions. If you have patches rejected multiple times, dont' be discouraged. You might consider finding a mentor willing to pre-review your patches before you send them to wine-patches (see http://www.winehq.org/pipermail/wine-devel/2010-August/086207.html for a discussion of this)

Special Situations

Submitting Patches Written by Somebody Else

Occasionally, the author of a useful patch stops working on it, and somebody else has to pick it up and continue. If you're simply resending a patch somebody else wrote, put a 'From:' line with the original author's name and email address in the explanation at the top of the email body. Keep all other formatting the same as it would have been in the original contributor's email.

The best way to handle abandoned patches though is by Patching your tree with the author's original patch file, including the correct authorship information. Then commit the changes and send the complete git format-patch output with all the headers, not just the diff, in the body of your mail. If the Wine maintainer's commit script detects an embedded git commit in the mail body it will ignore the actual SMTP headers in favor of the git info.

Creating Patches without Git

If you're set on not using Git for your patch, then it is possible to manage without. Be sure to still follow all the guidelines for good patches and code, and when you are finished. Then, obtain a unified diff (diff -u) between the unmodified and modified source trees, from the top of the source tree. Remember to save the diff as a .txt file if you will be attaching it, and stick to the same email guidelines you would use for a patch generated with git.

Multiple Outstanding Patchsets

Alexandre says you should concentrate on one thing and get it in before trying others. He may ignore some of your patchsets if he feels you have too many balls in the air.


CategoryDevelopment

SubmittingPatches (last edited 2013-08-15 16:09:22 by FrédéricDelanoy)