About This Guide

This is a series of guides intended to introduce software developers to the Wine ecosystem. It will cover what Wine is, how to use Wine, how to debug Wine, how to fix Wine, and what to do with your fix once you've made it.

• Part 1 describes what Wine is and provides a short description of various popular forks of Wine.
• Part 2 describes Wine's build process.
• Part 3 describes how to use Wine as a developer.
• Part 4 describes how to debug Wine in general.
• Part 5 describes Wine's source tree layout and how to edit the source.
• Part 6 describes how you can send your work upstream.

If you recall from Part 1, there are many forks of Wine. Where your fix belongs can vary depending on what fork of Wine you use, the nature of the bug you fixed, and how you fixed it.

Choosing the right place to send your fix

The ideal place for your fix is in upstream Wine. This is the origin point of all Wine forks. If you fix it in upstream Wine, then all users of Wine will eventually benefit from your work as the various forks pull in changes from upstream.

Sending your fix upstream should be the default choice for your work. If none of the exceptions below apply, or if you're unsure where your fix belongs, work with upstream first.

When upstream is the wrong choice

Your patch may be built on top of an existing patch in wine-staging. In that case, it should be sent to the wine-staging maintainers. If you, or they, think that the patch is ready to be sent upstream, then go ahead and do that instead.

If your patch fixes the issue, but you failed to fix the tests you wrote, or your patch causes some other test failures, it may belong on the bug tracker, or possibly in wine-staging.

If your patch provides a useful feature that upstream Wine is not interested in, it may belong in wine-staging.

If your patch is builds on a feature exclusive to some fork of Wine, like Proton or CrossOver, it may belong in that fork and not upstream. Work with the fork maintainers to determine if it's appropriate for upstreaming.

Upstreaming your fix

Hopefully, your patch is going upstream. Wine's patch submission process is done via email. Your patch should be sent in plain text to wine-devel@winehq.org. You should subscribe to this mailing list to avoid being placed into the moderation queue.

It is recommended to use git send-email to send the email through your mail server. You can also use git format-patch and attach the resulting file in an email client. Be careful that your mail client doesn't wrap, or otherwise corrupt, the attachment as if it were a text document.

Patches that are sent upstream should have your Sign-off. This can be applied by Git automatically with the -s switch during git commit and/or git format-patch. You must use your real name in the Author field when submitting a patch.

If you are submitting a series of patches, try to limit yourself to about four patches per submission. Your patches should be self-contained anyway, so there is no harm in submitting them in several batches. Smaller patch series are easier to review, and keep from cluttering up the mailing list if you have to re-send the series with changes.

Receiving feedback

Wine has a patch status webpage which will track the status of your patch. Your patch will be tested by the Wine Test Bot to ensure any new tests pass on various Windows versions. If the area of Wine changed by your patch has a maintainer, it will be assigned to that person for review. If not, it will be reviewed by the general community, or by the Wine maintainer.

Be patient, it may take a few days for your patches to receive review. Wine reviewers try to reply to every patch within a week, but if you don't get feedback you may send an email to wine-devel asking for a review. Be sure you are subscribed to wine-devel, as some reviews may be sent to that mailing list instead of directly back to the author.

If you received some suggestions, take those suggestions into account and send a new version of the patch. Feedback from Wine reviewers should not be seen as criticism or an attack. Wine is a very complicated piece of software, and it has a high standard of code quality for contributions. Rejections aren't made lightly—everyone wants Wine to improve. Instead, understand that there are reasons for the rejection, apply the suggestions, and resend the patch. If you do not have the time or interest in making the requested changes, consider sending your patch to wine-staging so some other person may take up the patch in the future and try to get it upstream. Or, attach it to a Bugzilla bug so it is not lost.

If your patch is accepted, then congratulations! You have just made Wine better. It's time to move on to the next bug.

Further reading

The WineHQ Wiki is the official place to find documentation about developing for the Wine project. Start here: https://wiki.winehq.org/Developers

If you have questions during your development, please reach out to the Wine developers on the wine-devel mailing list, or on the Libera Chat IRC network at #winehackers.

The text of this blog post is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

>>> CodeWeavers is a major contributor to the Wine project. Read More.

About Andrew Eikum
Andrew was a former Wine developer at CodeWeavers from 2009 to 2022. He worked on all parts of Wine, but specifically supported Wine's audio. He was also a developer on many of CodeWeavers's PortJumps.