-
Notifications
You must be signed in to change notification settings - Fork 156
Development
We are happy about everyone who would like to contribute patches to Wine Staging and we therefore collected the necessary information on this page. The rules are similar to upstream Wine with the difference that your patches don't have to be perfect from the beginning, but we will instead help you to improve them. In case you have questions, feel free to join our IRC channel #wine-staging on FreeNode.
Wine Staging is a testing version in preparation for patches to be submitted to upstream Wine, but not an arbitrary collection of Wine patches. We will not accept hacks for single applications and all patches must at least have a minimum standard quality. If your patch does not fulfill these quality guidelines, we will tell you about these problems, to give you the possibility to correct them. We are open for all other kind of patches and in contrast to upstream Wine, we also accept bigger work-in-progress patchsets.
You always need to develop your patch against the current git version of Wine. You can either apply all the existing Wine Staging patches or use an unpatched Wine source code. This only makes a difference if you try to extend existing patches.
As first step you should read the patch guidelines of Wine since they contain information about setting up git and the coding style of Wine. If you do not plan to directly send the patches upstream, you can stop reading at 'Writing the Email'. We assume that you know how to use git and won't explain this in detail, nevertheless here are some small tips on how to write a patch.
The first step is to make your changes to the Wine source code and to add them
as one or multiple commits. The subject for your commit should always have the
format module: Changes.. If you change something in ntdll, the subject would
look like:
ntdll: Remove all bugs from Wine.
If you are done with all your changes, you need to export them as patch files.
You can use the git format-patch command to create them.
git format-patch --keep-subject origin
You will now get one or multiple files starting from 0001-* which contain your changes. Now you only need to send us your patches.
The easiest way to submit patches is to create a bug report under "Patch Submission" containing the patch files and some additional description of the issue you are trying to resolve. For example, if your changes fix a particular bug or addresses an issue reported by a code analyzer (Coverity, etc).
Independent on how you send us your changes we will try to verify the correctness. Please be patient and give us up to about a week to review them - we're a very small team, so it might take some time, and we want to make sure that the implementation doesn't contain any critical errors, which could cause regressions. If you want to contribute huge sets of patches, we would really like you to stay contributing in the future. Even if we accepted your patches, this doesn't necessary mean we understand all of it, and if you cannot or don't want to maintain them (especially in case of errors, or difficult rebasing), we will probably end up removing them again.
You can also suggest adding patches written by other people - in this case your request should include who wrote the patch. Anonymous patches which don't include the author information aren't welcome, similar to the rules for upstream Wine.
Some files in the Wine git tree are autogenerated. If your patch modifies them, there is no need to include these changes - this will be done automatically by our Makefile when building Wine Staging.
Examples for files which are autogenerated:
/configure/include/server_protocol.h
The Wine Staging repository expects all patches to conform to Wine's (undocumented) attribution guidelines. There are a variety of ways to attribute patches, but they all involve an additional line to the patch subject:
commit 0000000000000000000000000000000000000000
Author: Example Author <example.email@email-provider.com>
Date: Sat Jul 26 12:31:50 2014 -0600
Name of patch.
TYPE-OF-ATTRIBUTION.
TYPE-OF-ATTRIBUTION can be any of the following:
Found/Spotted by FINDER.: The resolved issue was found by FINDER, they
should receive appropriate credit for finding the problem - even though
their patch was not used in the final implementation.
Based on a patch by AUTHOR.: The patch created by AUTHOR was a starting point
for the patch, some modifications were made to their patch - but they should
receive credit since the original implementation was theirs.
The Wine Staging repository contains a large number of patches which makes it impossible to manually ensure that there are no conflicts between different patchsets. In order to solve this issues and to check whether all patches still apply we use our own utility. This utility is written in python and also does some house keeping like updating the README.md file.
You will need to install the following programs in order to use the python script.
- python2.7
- patch
- diff
The utility needs to know the location of your Wine git source tree to check whether the patches still apply. You need to create symlink to the wine source directory using the following command:
ln -s /path/to/wine-source/ debian/tools/wine
The script will check the patches against the upstream version of the Wine
source code stored inside the .git directory, so your changes to the wine tree
won't have any affect on this check. You just need to call git fetch from time to time to ensure that your copy of the upstream source code is
up-to-date.
You could now manually call the python script debian/tools/patchupdate.py
before committing a patch to your local copy of Wine Staging, but we also
provide a pre-commit hook so that git will automatically call the script for
you. You can enable it by creating a symlink:
ln -s precommit-hook.sh .git/hooks/pre-commit
Now everything is set up and you can start adding patches.
Adding a patch is very easy. Simply create a subdirectory in patches/, copy the
patch files into it and commit the new files. The python script will now
automatically figure out dependencies, add your patch into the patch list etc.
You can also create a definition file inside the subdirectory to add
additional information which are used by our utility. Here is an example of such
a file:
Depends: wined3d-DXTn
Fixes: [33768] Fix texture corruption in CSI: Fatal Conspiracy
Fixes: [19231] Fix crash of Trine Demo on start
Fixes: [37391] Exception during start of fr-043 caused by missing DXTn support
The Depends line specifies that this patch series depends on some other
patches. This is necessary if there is some logical dependency between two patch
sets, for example if one patch does not work without the other one applied. If
the patches can be applied in any order you do not need to manually add such a
line. If your patchset depends on multiple other patchsets, you simply need to
add multiple Depends lines.
The Fixes line specifies that this patch series fixes a bug. The value inside
the brackets, for example 33768, defines a bug id inside of the WineHQ
bugtracker. The python script will automatically add a link to the bug tracker
entry inside of the README.md. If you fix a bug which does not have a WineHQ bug
number assigned, you simply leave out the brackets and the number. In this case
only the text is added to the README.md file.
We might add additional fields in the future, but these should be sufficient for regular patches.