My "Helping Applications Work" Guide

[Scott Ritchie]

I've recently finished up my "helping applications work" guide.  It's
meant to be something an end user with a problem application can read,
and if he has the will to learn how to help.

However, I'm not exactly sure where to put it on the winehq website.
Perhaps it should be linked from the main page of the applications
database, or from the support tab, or something.  Anyway, I'm posting it
here for peer review.

I've also sent it to wine-patches, but as I said nothing yet links to
it.

Thanks,
Scott Ritchie

----helping_applications.template----
<h1>How to help get applications working in Wine</h1>
<p>If you want to help get an application working in Wine, the first
thing you should do is register yourself in the applications database
and use one of your votes to indicate that you'd like more effort to be
spent on the application.  Every once in a while, a wine developer will
finish a project and look for something to do - combing through the
higher voted apps to find one that people need work on is a great way to
spend one's time and fill up a todo list.</p>
<p>If the application that you want working is not listed in the
applications database, there is an easy to use form available for you to
add it. <!-- link to form -->  If the application is in the database,
but lacks a maintainer you should consider becoming one.  If you are
familiar with wine and have a desire to test the application and help
get or keep it working, please apply by clicking the link in the
application's page.  Each application should have a supermaintainer,
and, if different versions of the application are substantially
different (such as in Internet Explorer), each subversion should have a
maintainer.  Please don't feel deterred by the need to apply to become a
maintainer - the application form is largely a formality to prevent
abuse and we can virtually guarantee your acceptance.</p>
<p>If you are the developer or publisher of the application, you
obviously have a very big incentive to help get your application working
under wine.  Fortunately, there are many options available to you other
than reporting bugs and hoping someone will fix them. By far the easiest
way is to simply send free copies of your software to wine developers
and hope they'll take an interest in getting it working.  You'd be
amazed how effective this approach can be, particularly for games. An
alternative option, perhaps more effective and expensive, is to pay wine
developers for their work on your application, either directly through a
negotiated contract or indirectly by posting a bounty. The most direct
method, however, is to help develop wine itself and contribute code
directly, which is exactly what Corel did for WordPerfect several years
ago.  In any case, making a post on the wine developers <a
href="http://www.winehq.org/site/forums">email list</a> can go a long
way.

<h2>If your application doesn't work:</h2>
<p>If your application experiences problems in a particular area, or
fails to even run at all, there are a number of steps you can take to
help us. The most important thing is to find out where exactly the
application is failing. To diagnose application problems, the first step
is to run the program from the console using wine, rather than from a
gui shortcut.  This will allow wine to output error messages to the
console, the understanding of which are key to solving the problem and
getting the application to work.</p>
<p>An application may not work because Wine doesn't yet fully implement
one of the DLL files the application is trying to use.  If you encounter
a DLL not found error, or see a lot of "FixMe:" messages while running
the application in wine, this is likely the case. When this occurs, you
can try using native (non-wine) DLL files in place of Wine's builtin
ones. Check the application database page for the program. There may be
special configuration options or instructions for installing native DLL
files there that you can try to get the application working. For further
configuration help, please see the <a
href="http://www.winehq.org/site/docs/wine-user/running">Running
Wine</a> section of the User Guide.</p>
<p>If the application still doesn't work, it's probably due to a bug or
deficiency in Wine and we'd like to hear about it.  Please see the <a
href="http://bugs.winehq.org/">reporting bugs</a> page for instructions
on how to best report bugs with applications.</p>


<h2>If your application does work, but with some difficulty:</h2>
<p>Sometimes, applications run under wine but they don't function quite
as smoothly as they do in windows.  They may have display errors, a
feature may be broken, or they may run unusually slow.  These
applications should receive a lower rating from their maintainers of
between 2 and 4 stars in the Application's Database, depending on the
degree of difficulty encountered.</p> <!-- See ratings guide link here
-->
<p>If you have found a way to make an application work that is more
complicated than simply installing it, please share that information by
posting on the application's page in the database.  If you are the
maintainer for the application, please post the instructions in a
"howto," which will appear inside green bars at the top of the
application's page.</p>


<h2>If your application used to work, but has since broken in a new
version of wine:</h2>
<p>Wine is a large and complex project, composed of many files written
by different authors.  Sometimes, an attempt to change a file and expand
support for one application will unexpectedly cause another application
to stop functioning.  These changes are known as "regressions", and they
are unfortunately sometimes found in the wine source code because the
author of a patch that causes a regression is quite simply unaware of
it.  Since the wine developers can't possibly test every application
with every patch, we have to rely on the community to inform us of when
regressions occur so that the problem can be easily identified and
ultimately fixed.  Without community involvement, regressions can go
unfixed for potentially very long periods of time.</p>
<p>If your application has experienced a regression, please try and
provide us with as much information as you can about when and how it
broke.  This allows us to isolate the exact thing we screwed up in the
code and provide a fix.  Please provide as much as you know about which
version of wine worked, and which version didn't, including the version
number and how you installed it (from source, binary packages, etc.)
Finally, please post these things in the Application Database page for
the app.</p>  
<p>If you wish to be extremely helpful, you can try to isolate the exact
patch which broke your application.  This takes quite a bit of time and
effort, but it is quite simply the best way to get your application
working again.  When it comes to fixing regressions, the only thing more
helpful to the wine developers than knowing exactly which patch caused a
regression is receiving a fix for the patch itself.  For help with
isolating problem patches, please see the documentation on <a
href="http://www.winehq.org/site/docs/wine-devel/x1375">regression
testing</a>.</p>