On 2011-06-26 09:42-0400 Hezekiah M. Carty wrote: > On Sat, Jun 25, 2011 at 2:45 PM, Alan W. Irwin > <ir...@beluga.phys.uvic.ca> wrote: >> >> Finally, I think we should make clear in README.release that the >> plcolorbar API is still considered to be experimental, and we should >> also discourage (by an appropriate post to plplot-devel) propagation >> to non-C languages until after we finalize the plcolorbar API during >> the next release cycle. At this time I don't actually plan any >> further API changes for plcolorbar, but we found we needed additional >> API changes once we became experienced with pllegend, and I suspect >> our plcolorbar experience will also be the same. >> > > I am bringing this on to the development list as I agree with this > both for plcolorbar and for new functions in general. I would like to > propose a new plplot-volatile.h header for the C API which would house > any new PLplot functions until they have had enough testing and use to > have a fixed API. For a simple function this may happen more or less > immediately, while more complex functions such as pllegend and > plcolorbar may live in plplot-volatile.h for a development release or > few. This provides a clear message to users and developers that the > function in question may still be in flux, and therefore so will any > code using it. > > There has been a lot of new development in the 5.9.x PLplot > development cycle so far, and I think this is a very good thing. > However, there have been a few occasions where APIs have changed after > a formal 5.9.x development release, requiring propagation of these > changes to all of the language bindings and statements in > README.release explaining the changes. My hope is that something > along the lines of a plplot-volatile.h header will simplify this > process somewhat. > > Any opinions on this?
Hi Hez: Thanks for bringing discussion of these issue to the attention of the list. I do have a concern; if you warn the users too much about new functionality, they will put off evaluating it, and you end up with having no user-suggested API changes until after we move the API from plplot-volatile.h and propagate it to all languages. So whatever mechanism we choose, it needs to be as encouraging as possible to tempt users to try the new functionality and to give us feedback about it. Also note that both pllegend and plcolorbar are extreme special cases. As Steve Schwartz commented to me off list a while ago, it is much easier to make a plot than a legend! Once the API for these functions has completely stabilized (BTW I think that has already happened with pllegend), then I suspect it will be years before we introduce anything with such complicated arguments as these two functions into PLplot again. So I don't think we should make a long-term PLplot policy in response to _just_ the special cases of these two functions. But see the paragraph after the next one below.... As far as users are concerned, I prefer the informal mechanism we have now where you warn them in README.release of any functionality where the API is still experimental. And normally that should be a light warning along the lines that we feel we have finalized this API and therefore strongly encourage users to experiment with it, but we are still open to change in that API if those that try it have further suggestions. We should probably use a heavier warning for the special case of plcolorbar for this release cycle since the fact is we will have very little experience with the latest version of the API for that function during this release cycle. As far as our developers are concerned, I think a warning not to propagate new and experimental C API might be sufficient on plplot-devel. OTOH, we do have a lot of new C API (and also old C API as well) that was designed for general use in all languages but never completed, i.e., it has not been documented, tested with a C example, and/or propagated to non-C languages. So some internal mechanism (say a special "unfinished function" section in plplot.h) that is transparent to users but which reminds PLplot developers of the unfinished nature of some of our C functions might be useful. If a C function is in that section, then the ideal result would be for its originator to finalize that API, then complete work on the function (i.e., by documenting it with both doxygen and docbook, by using it in at least one of our standard examples, and by propagating it to all languages [probably with some help from Jerry for Ada and Hez for OCaml]). Once completed, the function should be moved out of the "unfinished function" section of plplot.h. However, if those completion efforts don't happen in a reasonable length of time (say a couple of release cycles) because the originator and all other developers have lost interest in the new C API, then we should just move that functionality to pldeprecated.c with the goal of eventually removing it. To see how these criteria for the "unfinished function" section would work in practice, pllegend would not be in that section because it does have documentation, it is used in our standard examples, and it has been propagated to all languages. OTOH, plcolorbar would be in that section (even after my final changes for this release cycle) because of lack of documentation, lack of finalized version of the plcolorbar sections of examples 16 and 33, and (designed) lack of propagation because of the unfinished status of the -colorbar sections of those examples. As I have already discussed with Hez off list, I am rapidly running out of time I can spend on PLplot this summer, and I do plan to spend part of that remaining time in extensive Linux and wine testing of PLplot. So I hope to finish all my plcolorbar changes (which will consist of finalization of my bounding-box implementation efforts for plcolorbar) today. In addition, Hez has kindly agreed to taking over responsibility for expanding C example 33 to test the new functionality and flexibility I have put into plcolorbar. In the interests of getting out a release without too much further delay, I suggest any further plcolorbar changes he makes to example 33 (or 16) for this release cycle should be only for the special -colorbar option case (which insures by design that plcolorbar will not be tested by any of our automated tests). Then early in the next release cycle and after he has completed the plcolorbar tests in example 33 to his satisfaction, he can signal the start of propagation efforts for that function by removing the -colorbar optional infrastructure for C examples 16 and 33 so those C examples (and their counterparts for the other languages once plcolorbar has been propagated) always run plcolorbar. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ ------------------------------------------------------------------------------ All of the data generated in your IT infrastructure is seriously valuable. Why? It contains a definitive record of application performance, security threats, fraudulent activity, and more. Splunk takes this data and makes sense of it. IT sense. And common sense. http://p.sf.net/sfu/splunk-d2d-c2 _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
