WineHQ

Wine-Staging: Difference between revisions

(how to report bugs against staging)
Line 13: Line 13:
Since Wine-Staging is maintained as a set of patches rather than a forked repository, the process of building is slightly different. You will first need a vanilla Wine source tree and the required dependencies; for instructions see [[Building Wine]]. Note that Staging adds some optional dependencies which are necessary for certain additional features. You will also need the Staging "source"; this can be cloned or downloaded from [https://github.com/wine-staging/wine-staging the GitHub page].
Since Wine-Staging is maintained as a set of patches rather than a forked repository, the process of building is slightly different. You will first need a vanilla Wine source tree and the required dependencies; for instructions see [[Building Wine]]. Note that Staging adds some optional dependencies which are necessary for certain additional features. You will also need the Staging "source"; this can be cloned or downloaded from [https://github.com/wine-staging/wine-staging the GitHub page].


Once you have obtained the sources, you will need to apply the Staging patches of your choice (or all of them) on top of the Wine source tree. You can do this using the provided <tt>patches/patchinstall.sh</tt> script; see its options with --help for detailed instructions. If you apply patches manually, take note that you will also need to run <tt>autoreconf -f</tt> and <tt>tools/make_requests</tt>, as such generated changes are not included in Staging patches. Be warned that an individual version of the Staging repository will ''only'' successfully apply against the upstream Wine commit it was last rebased against.
Once you have obtained the sources, you will need to apply the Staging patches of your choice (or all of them) on top of the Wine source tree. You can do this using the provided <tt>patches/patchinstall.sh</tt> script; see its options with <tt>--help</tt> for detailed instructions. If you apply patches manually, take note that you will also need to run <tt>autoreconf -f</tt> and <tt>tools/make_requests</tt>, as such generated changes are not included in Staging patches. Be warned that an individual version of the Staging repository will ''only'' successfully apply against the upstream Wine commit it was last rebased against.


After you have applied patches, compilation proceeds as usual for upstream Wine; refer to [[Building Wine]] for detailed instructions.
After you have applied patches, compilation proceeds as usual for upstream Wine; refer to [[Building Wine]] for detailed instructions.
== Reporting and debugging bugs against Staging ==
We, the Staging maintainers, really need to know whether a bug is introduced by a Staging patch, or has nothing to do with any Staging patches. If a bug is introduced by a Staging patch, it suggests that something is wrong with the patch in question, and that patch needs to be fixed before it can be sent upstream.
Therefore, when reporting a bug against Staging, '''always''' test '''both''' the '''latest''' Staging and upstream releases. If the bug is also present in the same form with upstream Wine, the bug should be reported against the Wine product, not the Wine-Staging product. Doing this saves ''everyone'' a lot of time and effort.
If the bug is present in Wine-Staging but not in upstream Wine, then the next most helpful thing to do is to bisect between Staging and Wine. In order to do this, you'll first want to acquire a clean Wine tree as well as the latest set of Staging patches. Next, apply each patch as a separate commit, using the command
<pre>path/to/staging-tree/patches/patchinstall.sh --all --backend=git-am --force-autoconf</pre>
either in your Wine source tree, or using the <tt>DESTDIR</tt> argument. You'll need to use the <tt>--force-autoconf</tt> argument to ensure that patches affecting configure.ac or protocol.def are properly applied; alternatively, you can omit this argument, so long as you remember to run it before compiling each step of the bisect. From here the bisect should proceed as normal; you can find some (admittedly rather outdated) instructions [[Regression Testing|here]].
=== Regressions between Staging versions ===
Suppose a failure is introduced in a later Staging version, that does not occur in an earlier one. This, again, could mean one of several things, each of which have a vastly different significance. There could be a bug introduced by a new Staging patch, or (re)introduced by losing one; there could be an error during rebasing, or an obscure way in which a change upstream breaks a Staging patch. Alternatively, there could be a problem introduced or exposed by a patch committed upstream, that is, a regression strictly in upstream Wine. Again, we really need to know which one of these things has happened. Therefore, we will again ask you, before you do anything else, to test the corresponding upstream Wine releases of both the "good" version and the "bad" version.
If both the "old" and "new" upstream Wine releases are not affected by the bug, it's a bug in Staging, and should be reported against the Wine-Staging product. In this case, it's again most helpful to then perform a regression test between Staging and Wine, as detailed above.
If the "old" upstream Wine release is not affected by the bug, but the "new" one is, we can pretty safely assume it's a bug in upstream Wine. In that case, the bug should be reported against the Wine product. From here the most helpful thing to do is perform a regression test between upstream Wine releases.
If the application does not work using upstream Wine to the point of triggering the bug in question—that is, it fails too early, but that failure is fixed by a Staging patch—the same principle applies, but is muddied by the additional presence of Staging patches. We first need to know exactly ''which'' Staging patches fix the earlier bug. This might be documented on bugs attached the application in our AppDB, or it may only be mentioned on the bugs themselves (in the latter case, please do submit bug links to the AppDB). It also may not be known at all, in which case you'll need to perform a ''reverse'' bisect between Wine-Staging and upstream Wine, of the last known working version—that is, a bisect where the meanings of "bad" and "good" are reversed. You may have to perform multiple such bisects, if the application depends on multiple Staging patches.
Once you've identified exactly which patches are necessary before the failure can be reproduced, the next step is to try applying only those patches against a clean upstream Wine of the earliest broken version. If the failure is not present, this implies something was broken in Staging. Figuring out what can be difficult, and is probably very dependent on circumstances, so this guide won't prescribe any further course of action at the present moment. If the failure is present, this implies something was broken in upstream Wine. In that case the next step is to perform a bisect between upstream Wine versions, as normal—except at every step you'll also need to apply the Staging patches that are necessary for the application to run.
This may seem like a lot of bisects and testing to perform—and it is, but it really is the easiest way for a problem to be fixed. It may be easiest for the user to simply pull a debug log with given flags, but in the vast majority of cases, it's orders of magnitude easier to fix a bug if it's known exactly what patch introduces that bug. Making things easier for developers is by far the best route to getting a bug fixed quickly. At the same time, we recognize that bisects are time-consuming for anyone to perform, and we will understand if you can't spare the time to perform them—as long as you understand in turn that your bug is not by any means guaranteed to be fixed quickly. However, we will always expect you to have tried upstream Wine first.


== Quick Links ==
== Quick Links ==

Revision as of 02:17, 21 September 2019

What is Wine Staging?

Wine Staging is the testing area of winehq.org. It contains bug fixes and features, which have not been integrated into the development branch yet. The idea of Wine Staging is to provide experimental features faster to end users and to give developers the possibility to discuss and improve their patches before they are integrated into the main branch.

Wine Staging is maintained as a set of patches which has to be applied on top of the corresponding Wine development version. Package maintainers can decide if they want to include our full patchset, or only want to cherry-pick patches for specific bugs.

Installation

Pre-compiled Staging packages for most major distributions are available on the Download page. Instructions for installing Staging are given under each distribution that provides it.

Building from source

Since Wine-Staging is maintained as a set of patches rather than a forked repository, the process of building is slightly different. You will first need a vanilla Wine source tree and the required dependencies; for instructions see Building Wine. Note that Staging adds some optional dependencies which are necessary for certain additional features. You will also need the Staging "source"; this can be cloned or downloaded from the GitHub page.

Once you have obtained the sources, you will need to apply the Staging patches of your choice (or all of them) on top of the Wine source tree. You can do this using the provided patches/patchinstall.sh script; see its options with --help for detailed instructions. If you apply patches manually, take note that you will also need to run autoreconf -f and tools/make_requests, as such generated changes are not included in Staging patches. Be warned that an individual version of the Staging repository will only successfully apply against the upstream Wine commit it was last rebased against.

After you have applied patches, compilation proceeds as usual for upstream Wine; refer to Building Wine for detailed instructions.

Reporting and debugging bugs against Staging

We, the Staging maintainers, really need to know whether a bug is introduced by a Staging patch, or has nothing to do with any Staging patches. If a bug is introduced by a Staging patch, it suggests that something is wrong with the patch in question, and that patch needs to be fixed before it can be sent upstream.

Therefore, when reporting a bug against Staging, always test both the latest Staging and upstream releases. If the bug is also present in the same form with upstream Wine, the bug should be reported against the Wine product, not the Wine-Staging product. Doing this saves everyone a lot of time and effort.

If the bug is present in Wine-Staging but not in upstream Wine, then the next most helpful thing to do is to bisect between Staging and Wine. In order to do this, you'll first want to acquire a clean Wine tree as well as the latest set of Staging patches. Next, apply each patch as a separate commit, using the command

path/to/staging-tree/patches/patchinstall.sh --all --backend=git-am --force-autoconf

either in your Wine source tree, or using the DESTDIR argument. You'll need to use the --force-autoconf argument to ensure that patches affecting configure.ac or protocol.def are properly applied; alternatively, you can omit this argument, so long as you remember to run it before compiling each step of the bisect. From here the bisect should proceed as normal; you can find some (admittedly rather outdated) instructions here.

Regressions between Staging versions

Suppose a failure is introduced in a later Staging version, that does not occur in an earlier one. This, again, could mean one of several things, each of which have a vastly different significance. There could be a bug introduced by a new Staging patch, or (re)introduced by losing one; there could be an error during rebasing, or an obscure way in which a change upstream breaks a Staging patch. Alternatively, there could be a problem introduced or exposed by a patch committed upstream, that is, a regression strictly in upstream Wine. Again, we really need to know which one of these things has happened. Therefore, we will again ask you, before you do anything else, to test the corresponding upstream Wine releases of both the "good" version and the "bad" version.

If both the "old" and "new" upstream Wine releases are not affected by the bug, it's a bug in Staging, and should be reported against the Wine-Staging product. In this case, it's again most helpful to then perform a regression test between Staging and Wine, as detailed above.

If the "old" upstream Wine release is not affected by the bug, but the "new" one is, we can pretty safely assume it's a bug in upstream Wine. In that case, the bug should be reported against the Wine product. From here the most helpful thing to do is perform a regression test between upstream Wine releases.

If the application does not work using upstream Wine to the point of triggering the bug in question—that is, it fails too early, but that failure is fixed by a Staging patch—the same principle applies, but is muddied by the additional presence of Staging patches. We first need to know exactly which Staging patches fix the earlier bug. This might be documented on bugs attached the application in our AppDB, or it may only be mentioned on the bugs themselves (in the latter case, please do submit bug links to the AppDB). It also may not be known at all, in which case you'll need to perform a reverse bisect between Wine-Staging and upstream Wine, of the last known working version—that is, a bisect where the meanings of "bad" and "good" are reversed. You may have to perform multiple such bisects, if the application depends on multiple Staging patches.

Once you've identified exactly which patches are necessary before the failure can be reproduced, the next step is to try applying only those patches against a clean upstream Wine of the earliest broken version. If the failure is not present, this implies something was broken in Staging. Figuring out what can be difficult, and is probably very dependent on circumstances, so this guide won't prescribe any further course of action at the present moment. If the failure is present, this implies something was broken in upstream Wine. In that case the next step is to perform a bisect between upstream Wine versions, as normal—except at every step you'll also need to apply the Staging patches that are necessary for the application to run.

This may seem like a lot of bisects and testing to perform—and it is, but it really is the easiest way for a problem to be fixed. It may be easiest for the user to simply pull a debug log with given flags, but in the vast majority of cases, it's orders of magnitude easier to fix a bug if it's known exactly what patch introduces that bug. Making things easier for developers is by far the best route to getting a bug fixed quickly. At the same time, we recognize that bisects are time-consuming for anyone to perform, and we will understand if you can't spare the time to perform them—as long as you understand in turn that your bug is not by any means guaranteed to be fixed quickly. However, we will always expect you to have tried upstream Wine first.

Quick Links

Here are some links to the most important topics.

https://github.com/wine-staging/wine-staging Usage
Configuration
Contributing
Bugs

See Also

Wine-staging GitHub repository

This page was last edited on 21 September 2019, at 02:17.