wine/wine-staging
0
0
Fork 0
mirror of https://gitlab.winehq.org/wine/wine-staging.git synced 2024-09-13 09:17:20 -07:00
Code Issues Packages Projects Releases Wiki Activity
Page: home
Pages
Configuration Contributing Packaging Usage home
1 home
Alexandre Julliard edited this page 2024-09-04 11:16:44 +02:00
Table of Contents
title
Wine Staging

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.

The current Wine-Staging team is:

  • Alistair Leslie-Hughes (lead maintainer)
  • Dean Greer
  • Paul Gofman
  • Thomas Crider
  • Zeb Figura

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 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.

Submitting patches

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). You must use your real name.
  • Like upstream Wine, we cannot take contributions from anyone who has disassembled or reverse-engineered Microsoft code, or seen sources (whether leaked or publicly available).

How to submit

Since we need a bug report anyway, the ideal way to submit a patch is simply to attach it to the given bug report. 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 Zeb 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.

We may ask you to submit your patch upstream first if it seems good enough already. Remember that Wine-Staging is never the ultimate goal for a patch; all patches should eventually get into upstream Wine.

Maintaining Staging

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.

Organization

The layout of the Staging repository is mostly self-explanatory. The staging/ directory contains tools to maintain the patches, and the patches/ directory contains the patches themselves, as well as the `patchinstall.sh` script to install them.

Each set of patches is contained within a single folder, labeled `component-Short_Description`, where the component is the most salient DLL or source directory (as with upstream Wine). Each set contains one or more patches, plus a `definition` file. This latter file uses a relatively simple format that looks like this:

Fixes: [10000] The original win32 api implementation is still more popular than wine.
Depends: ntdll-Some_Dependency
Depends: server-Another_Dependency
Disabled: true

The Fixes: line was historically used by a tool that would check whether a linked bug was still open. That tool was rarely useful and has been removed. Specifying it is still a convenience, though. At any rate any new patch set added to the tree *must* have a corresponding bug linked somewhere, either in the patches themselves or in the definition file.

Each Depends: line gives the name of a patch set that must be applied before this one is applied. Sometimes this dependency is given for the purpose of functionality; i.e. this patch simply won't work without its dependency also applied. More often it's given because the two patches touch closely related code, and the diffs would conflict if they were applied independently.

A Disabled: line may be added if necessary. We try to avoid this if at all possible. A disabled patch is not being maintained, is not being rebased, is not being tested, and is really useless to everyone, with the exception that it's at least visible if anyone wants to look for it. The line may be omitted if the patch is not disabled (i.e. you don't have to put false).

Rebasing

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:

  1. 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.
  2. From wine-staging/, run ./staging/newupdate.py.
  3. If applying the patches fails, repeat the following until it succeeds:
    1. From wine/, run wine-staging/staging/patchinstall.py -r <name-Of_Patchset>. This will fail inside of git-am.
    2. Run git am --show-current-patch | patch -p1.
    3. Resolve conflicts manually if fuzz detection wasn't enough.
    4. Run git add -u && git am --continue. You may need to also manually git add files that were added by the patch.
    5. Run git format-patch -N -1 --no-signoff, and replace the previous patch with that. Alternatively, replace -1 with a larger number. Try to avoid changing the filename, though; it makes things more difficult to trace. I usually just generate a patch and then cp it onto the old filename. You can omit --no-signoff by configuring format.signOff to false.
    6. Make sure the updated diff makes sense—things didn't get applied in completely the wrong place, upstream code didn't change to break the functionality of the new changes. I often just read the diff of the diffs, at a certain point it's easy enough to tell
    7. Run git reset --hard origin && git clean -df and go back to step 2.
  4. Build Wine.
  5. Run winecfg, at least; make sure wine isn't completely broken. We don't hold wine-staging to nearly as high a standard as upstream wine, mostly because we simply don't have the time (note also that currently many tests are broken on wine-staging anyway).
  6. Run ./staging/commit-rebase.sh.
  7. Push.

Quick Links

Here are some links to the most important topics.