Import pages from MediaWiki. authored by Alexandre Julliard's avatar Alexandre Julliard
---
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](https://gitlab.winehq.org/wine/wine-staging) 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](https://gitlab.winehq.org/wine/wine/-/wikis/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](https://gitlab.winehq.org/wine/wine/-/wikis/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](https://gitlab.winehq.org/wine/wine-staging).
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](https://gitlab.winehq.org/wine/wine/-/wikis/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](https://gitlab.winehq.org/wine/wine/-/wikis/Regression-Testing).
### 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](https://gitlab.winehq.org/wine/wine/-/wikis/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.
- [Usage](Usage)
- [Configuration](Configuration)
- [Contributing](Contributing)
- [Bugs](https://bugs.winehq.org/buglist.cgi?bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=STAGED&amp;bug_status=REOPENED&amp;bug_status=NEEDINFO&amp;bug_status=RESOLVED&amp;list_id=610554&amp;product=Wine-staging&amp;query_format=advanced)