On Tue, May 19, 2009 at 12:02:09AM +0200, Eric Lemoine wrote: > thanks a lot for putting this email together Chris, shall we > copy&paste it somewhere for future reference?
Yeah: I'm not sure if it amkes more sense as a wikipage, or someplace in the docs. I figured I'd write it, and let someone else do that part if they cared :) -- Chris > -- > Eric > > On Friday, May 15, 2009, Christopher Schmidt <[email protected]> wrote: > > Hi, > > > > (Cross-posted to dev and users: please send all replies to the users list.) > > > > Many times, users have come to me, or asked questions in IRC, related to > > getting help with a particular behavior. Whether that behavior is a bug > > or user error, there is one thing that you can do to make it more > > likely that a developer will be able to quickly help you with your > > problem. (In some cases, this is the difference between getting help at > > all, and simply not receiving any.) I have never seen any situation > > where this rule does not apply, and so I want to share it publicly with > > the users and dev communities so that we can all learn from it, and > > learn how to help each other more quickly and easily. > > > > (Throughout this post, I use the terms 'developers' and 'users'. By > > these terms, I mean "persons who have knowledge of the code inside of > > the OpenLayers library" and "persons who have knowledge of using the > > OpenLayers library, but not what is inside the library itself.") > > > > Minimizing Test Cases > > --------------------- > > > > In order for developers to help fix a problem, they first have to > > understand it. In order to do that, they need to understand everything > > thati s going on in a situation where the problem is reproducible. > > Oftentimes, the particular behavior is only existing in a certain type > > of situation, or in a limited case that is not exploited by the commonly > > used code. (In addition, some problems are the result of user error in > > some way.) > > > > In order to help developers help you, the best thing to do is to > > minimize the error to the *smallest amount of code that can cause it to > > happen*. Additionally, when attempting to reproduce, any developer will > > need to set up the code so that it is possible to run in the developer's > > test environment. This means that it is ideal to remove external > > references to other Javascript files, and external files at all, where > > possible. (Clearly, this is not always possible: WFS server bugs can't > > typically be demonstrated inside of a single page, for example -- but > > you should minimize external dependancies as much as possible.) > > > > Once you've done this, you should remove *all non-neccesary lines of > > code* from your example. Does the problem require the ScaleBar control > > in order to manifest itself? If not, toss it. Does it need multiple > > layers? If not, toss them. In short, any line of code that is not > > directly related to reproducing the problem should be removed, as each > > line will need to be read by the developer -- and in the case of > > multiple developers working on a problem, read by *each* developer -- in > > order to determine whether the problem is related to that. > > > > This minimization step should include removing any unneccesary > > Javascript, unneccesary CSS files, unneccesary HTML, etc. until the > > resulting code is as small as possible. > > > > Many times, in doing this, you will come across a particular > > minimization step that causes the problem to go away. This is a good > > sign, because it means you have narrowed the problem down to that > > particular aspect of code. Put it back, and keep minimizing. > > > > Additionally, many times in doing this, you find a particular construct > > in your code that can help you understand how to work around the > > problem. > > > > If not, then continue onto the next section. > > > > OpenLayers Library References > > ============================= > > > > There are multiple hosted versions of the OpenLayers library. > > > > http://openlayers.org/api/OpenLayers.js > > > > This will always represent the most recent released 'stable' version of > > the OpenLayers API. > > > > http://openlayers.org/dev/OpenLayers.js > > > > This is always a 10-minute delayed build of OpenLayers trunk. > > > > To simplify allowing developers to set up the code on their own testing > > environments, it is often beneficial to point directly to one of these > > library URLs. In addition, this also ensures that the problem is not > > something specific to your build of OpenLayers. > > > > Publishing your Problem > > ----------------------- > > > > Once you have minimized your test case, you need to publish it. In > > general, it is easiest if you publish an HTML page on a web accessible > > URL. Even if your project is not yet public, you can likely put a page > > up on another server which demonstrates the problem. Doing this is much > > more likely to have a developer actually follow the link and explore > > your problem. This is *especially* true for things like WFS which > > require a proxy to work correctly: Downloading the page, setting up a > > proxy, and testing locally is a lot of work for a developer simply to > > confirm that a problem exists. > > > > If you do not have *any* place to publish webpages, you can attempt to > > paste your code to a public site like 'nopaste.com'. However, be aware > > that doing so means that a developer has to perform more steps to > > reproduce your problem -- and every step is one that makes the problem > > less likely to be solved quickly and easily. > > > > Communicating about your Problem > > -------------------------------- > > > > The best way to communicate your problem is to send an email to the > > users list demonstrating the problem. Oftentimes other users will be > > able to point out a particular flaw in your code that is causing the > > error, or explain that the behavior is a known lack of functionality in > > OpenLayers. > > > > *Be clear on steps for reproduction*. Users who don't know what they're > > supposed to do to cause the bug will not be able to see it, and if they > > can't see it, they can't help you. > > > > If you have determined the particular change in the OpenLayers source > > code which is required to change the behavior, then it is more likely > > that the Developers list is the best place to go. Any discussion which > > involves code from OpenLayers itself is probably better suited for the > > dev list. > > > > Finally, > > -------- > > > > By following the steps: > > * Simplify/Minimize > > * Publish > > * Communicate > > > > (If you'd like, you can toss a "???, Profit!" at the end of this.) > > > > You can ensure that it is as easy as possible for a developer to > > determine whether the problem you're having is with the library. You > > also make it easier for develpoers and users to find potential problems > > in your usage of the library and suggest solutions. Finally, you may > > find in the process that you find the bug yourself, thus saving yourself > > and everyone else time in trying to debug. > > > > The end result is a more workable system for everyone. The easier it is > > to understand the problem you're having, the faster, and more easily, > > you will be able to get help. > > > > Best Regards, > > -- > > Christopher Schmidt > > MetaCarta > > _______________________________________________ > > Dev mailing list > > [email protected] > > http://openlayers.org/mailman/listinfo/dev > > > > -- > Eric Lemoine > > Camptocamp France SAS > Savoie Technolac, BP 352 > 73377 Le Bourget du Lac, Cedex > > Tel : 00 33 4 79 44 44 96 > Mail : [email protected] > http://www.camptocamp.com > _______________________________________________ > Users mailing list > [email protected] > http://openlayers.org/mailman/listinfo/users -- Christopher Schmidt MetaCarta _______________________________________________ Users mailing list [email protected] http://openlayers.org/mailman/listinfo/users
