Difference between revisions of "Wine-Staging Development"

From WineHQ Wiki
Jump to: navigation, search
(Add this page to the "Wine-Staging Contributing" category.)
(rewrite)
 
Line 1: Line 1:
 
[[Category:Wine-Staging Contributing]]
 
[[Category:Wine-Staging Contributing]]
  
We are happy about everyone who would like to contribute patches to Wine Staging
+
We welcome everyone, old and new contributors alike, to contribute new patches to Wine-Staging. Our primary goal is to offer a place for large, incomplete, or risky patchsets to be tested and maintained until they are ready for inclusion into upstream Wine. For new developers, we also try to provide a more helpful and less demanding environment to get acquainted with the Wine project.
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.
 
  
== The kind of patches we are looking for ==
+
== Requirements ==
  
Wine Staging is a '''testing version''' in preparation for patches to be submitted
+
Our standards are less strict than upstream Wine, but we do still have some requirements:
to upstream Wine, but not an arbitrary collection of Wine patches. We will not
+
* The patch must be a step in the right direction; that is, we don't allow patches that are gross hacks, or take an obviously wrong approach to solving a problem. The end goal is always to submit the patch upstream eventually, so work should progress in that direction.
accept hacks for single applications and all patches must at least have a
+
* The patch must have a bug attached. We place great value on traceability, so we require all patches to have an associated WineHQ bug (exceptions may be granted under special circumstances). We also strongly encourage all discussion to take place on the relevant bug.
minimum standard quality. If your patch does not fulfill these quality
+
* Like upstream Wine, a patch must have correct attribution. If you did not write a patch, you must make this clear (ideally using the From: line in the patch itself).
guidelines, we will tell you about these problems, to give you the possibility
+
* Unlike upstream Wine, we do not require sign-offs. We take sign-offs to mean the same thing as they do for upstream Wine: that you consider your code to be good enough to go into upstream Wine and to meet all of the legal and technical requirements thereof; accordingly a sign-off is not necessary for Staging patches, which do not need to meet these requirements. However, if you do provide a sign-off, be aware that your sign-off may be preserved by someone else who submits the patch upstream.
to correct them. We are open for all other kind of patches and in contrast to
+
* Like upstream Wine, we do not take contributions from anyone who has disassembled or reverse-engineered Microsoft code, or seen sources (whether leaked or publicly available).
upstream Wine, we also accept bigger work-in-progress patchsets.
 
  
== Writing a Patch ==
+
== Submitting new patches ==
  
You always need to develop your patch against the current git version of Wine.
+
We prefer new patches to be submitted using [http://bugs.winehq.org/ WineHQ Bugzilla]. If you have a patch (or patch set) which fixes a bug and you'd like it to be included in staging, please attach it to the bug as a patch against Wine (rather than against the Wine-Staging tree itself). Instructions for how to create patches against Wine can be found at [[Submitting Patches]]. If you have several patches, please compress them into a single tarball or zip instead of attaching each one individually. Then, CC or e-mail Alistair Leslie-Hughes (leslie_alistair AT SPAMFREE hotmail DOT com) and Zebediah Figura (z DOT figura 12 AT SPAMFREE gmail DOT com) on the bug asking for acceptance into Staging. Please be explicit and provide details about the patch if you can, and tell us why you are submitting the patch into Staging rather than upstream Wine. If accepted, we will add your patch into the Staging tree, creating the definition files and updating the install script as necessary.
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 [[Submitting Patches]] 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 <code>module: Changes.</code>. If you change something in ntdll, the subject would
 
look like:
 
<pre>ntdll: Remove all bugs from Wine.</pre>
 
 
 
If you are done with all your changes, you need to export them as patch files.
 
You can use the <code>git format-patch</code> command to create them.
 
<pre>git format-patch --keep-subject origin</pre>
 
 
 
You will now get one or multiple files starting from 0001-* which contain your
 
changes. Now you only need to send us your patches.
 
 
 
== Submitting patches ==
 
 
 
The easiest way to submit patches is to create a
 
[https://bugs.wine-staging.com/ 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.
 
 
 
=== Autogenerated Wine files ===
 
 
 
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:
 
* <code>/configure</code>
 
* <code>/include/server_protocol.h</code>
 
 
 
=== Attribution guidelines ===
 
 
 
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:
 
<pre>
 
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.</pre>
 
 
 
TYPE-OF-ATTRIBUTION can be any of the following:
 
 
 
<code>Found/Spotted by FINDER.</code>: 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.
 
 
 
<code>Based on a patch by AUTHOR.</code>: 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.
 
 
 
== Patch management (Maintainers only) ==
 
 
 
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.
 
 
 
=== Setup ===
 
 
 
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:
 
<pre>ln -s /path/to/wine-source/ debian/tools/wine</pre>
 
 
 
The script will check the patches against the upstream version of the Wine
 
source code stored inside the <code>.git</code> directory, so your changes to the wine tree
 
won't have any affect on this check. You just need to call <code>git fetch</code> 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 <code>debian/tools/patchupdate.py</code>
 
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:
 
<pre>ln -s precommit-hook.sh .git/hooks/pre-commit</pre>
 
 
 
Now everything is set up and you can start adding patches.
 
 
 
=== Adding patches ===
 
 
 
Adding a patch is very easy. Simply create a subdirectory in <code>patches/</code>, 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 <code>definition</code> file inside the subdirectory to add
 
additional information which are used by our utility. Here is an example of such
 
a file:
 
<pre>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</pre>
 
 
 
The <code>Depends</code> 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 <code>Depends</code> lines.
 
 
 
The <code>Fixes</code> 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.
 

Latest revision as of 04:29, 5 July 2018


We welcome everyone, old and new contributors alike, to contribute new patches to Wine-Staging. Our primary goal is to offer a place for large, incomplete, or risky patchsets to be tested and maintained until they are ready for inclusion into upstream Wine. For new developers, we also try to provide a more helpful and less demanding environment to get acquainted with the Wine project.

Requirements

Our standards are less strict than upstream Wine, but we do still have some requirements:

  • The patch must be a step in the right direction; that is, we don't allow patches that are gross hacks, or take an obviously wrong approach to solving a problem. The end goal is always to submit the patch upstream eventually, so work should progress in that direction.
  • The patch must have a bug attached. We place great value on traceability, so we require all patches to have an associated WineHQ bug (exceptions may be granted under special circumstances). We also strongly encourage all discussion to take place on the relevant bug.
  • Like upstream Wine, a patch must have correct attribution. If you did not write a patch, you must make this clear (ideally using the From: line in the patch itself).
  • Unlike upstream Wine, we do not require sign-offs. We take sign-offs to mean the same thing as they do for upstream Wine: that you consider your code to be good enough to go into upstream Wine and to meet all of the legal and technical requirements thereof; accordingly a sign-off is not necessary for Staging patches, which do not need to meet these requirements. However, if you do provide a sign-off, be aware that your sign-off may be preserved by someone else who submits the patch upstream.
  • Like upstream Wine, we do not take contributions from anyone who has disassembled or reverse-engineered Microsoft code, or seen sources (whether leaked or publicly available).

Submitting new patches

We prefer new patches to be submitted using WineHQ Bugzilla. If you have a patch (or patch set) which fixes a bug and you'd like it to be included in staging, please attach it to the bug as a patch against Wine (rather than against the Wine-Staging tree itself). Instructions for how to create patches against Wine can be found at Submitting Patches. If you have several patches, please compress them into a single tarball or zip instead of attaching each one individually. Then, CC or e-mail Alistair Leslie-Hughes (leslie_alistair AT SPAMFREE hotmail DOT com) and Zebediah Figura (z DOT figura 12 AT SPAMFREE gmail DOT com) on the bug asking for acceptance into Staging. Please be explicit and provide details about the patch if you can, and tell us why you are submitting the patch into Staging rather than upstream Wine. If accepted, we will add your patch into the Staging tree, creating the definition files and updating the install script as necessary.