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.
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 GitLab 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 staging/patchinstall.py script (introduced with wine-staging 5.6, for earlier versions use patches/patchinstall.sh); 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/staging/patchinstall.py --all --backend=git-am --force-autoconf -d path/to/wine/source/dir
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.
At the time of this writing, none of the Staging maintainers plan to go anywhere. Nevertheless, so that all future hand-offs proceed smoothly, I've attempted to document the general process of maintaining Staging below, or at least the parts that particularly need instructions.
We currently rebase staging onto upstream wine after every daily commit round. We could do it less often, but this has a tendency to make changes pile up and become much more difficult to deal with. The point of rebasing is to change the patches to apply directly on top of upstream. We have scripts to make this relatively simple.
I keep a separate git worktree, which is entirely clean (no untracked files) so that I can just run git clean -df to wipe artifacts of rebasing.
Starting from an up-to-date source tree wine/ and a not yet rebased staging tree wine-staging/, my process of rebasing goes like this:
- Examine the day's commit list and remove any Staging patches which were upstreamed or obviated. Make sure to do this, as patches which were upstreamed without changes will be silently ignored by git-am.
- From wine-staging/, run ./staging/newupdate.py.
- If applying the patches succeeds, go to step 10.
- From wine/, run wine-staging/staging/patchinstall.py -r <name-Of_Patchset>. This will fail inside of git-am.
- Run git am --show-current-patch | patch -p1.
- Resolve conflicts manually if fuzz detection wasn't enough.
- Run git add -u && git am --continue. You may need to manually git add files that were added by the patch.
- Run git format-patch -1 --no-signoff, and replace the previous patch with that.
- Run git reset --hard origin && git clean -df and go back to step 2.
- Build Wine.
- Run winecfg, at least.
- Commit the rebase, putting the SHA of the upstream Wine commit in the message.
Here are some links to the most important topics.