rod> I'm +1 on establishing a release plan for httpclient
rod> and moving quickly to execute it, but I think I'm -0
rod> for releasing it as it stands [...]
rod> for the following reasons:
rod>
rod> a) Over the past couple of weeks there have been several
rod> significant fixes implemented [...]
rod> I wonder what else might be lurking
rod> out there, and I suspect we haven't cleanly and clearly
rod> specified the "contract" of httpclient and how it should
rod> behave.
remy> Just in case, I'm actually using it for the WebDAV
remy> command line client. This client has been tested at
remy> an interoperability event against a large variety of
remy> HTTP / WebDAV servers (http://www.webdav.org/other/interop.html).
remy> It worked well, so it appears that if there are some
remy> issues, there are not critical issues which would make
remy> us delay a release.
Right, and as I mentioned previously, we're using it in a critical
production application, as well as in a HTTP/S testing tool we use multiple
times a day during development. I'm confident that the pieces of httpclient
that we exercise in these apps work fine, just as I'm confident that the
pieces of httpclient you exercise in the WebDAV client work fine too.
But I also know that when we started to use httpclient for the
aforementioned apps, there were several aspects that simply didn't work, or
didn't work as advertised, or that were sufficiently confusing that what we
expected them to do and what they actually did were different. Clearly
these were aspects of httpclient that the WebDAV codebase wasn't using, and
hence had never been sufficiently tested. (Look back over the logs when
Morgan, Doug and I started poking around at it and you'll see what I mean.)
I'd be willing to bet that one or more of these three conditions
(undiscovered defects, documentation bugs, or unclear/unspecified behavior
specifications) still applies to httpclient, lurking in the areas that have
not been extensively used (or used at all).
Moreover, I'd suggest that the most significant problems lie in the latter
two conditions, where the behavior of httpclient has changed but not the
interface (witness the deprecated constructors, etc.) or where the
implementation of some feature was initiated but never completed, etc.
rod> b) On a related note, there is literally no documentation
rod> for httpclient outside of the java code itself, and what
rod> we see there is fairly sparse.
remy> Good idea.
remy> However :
remy> - None of the other components have any docs, except Cactus
And I see that as a problem too. Frankly I wouldn't advocate releasing any
component without at minimum putting up a page or two dedicated to it on the
jakarta site. (Collections at least is fairly self-explanatory, and
digester and beanutils are relatively small, but I don't think they should
have been released sans-documentation either. I would have pushed for a
collections release, and probably pool and dbcp too, a long time ago were it
not for the absence of documentation.)
remy> - I really don't have time to do it; since nobody has
remy> volunteered to do it (and you didn't), I assume it just
remy> won't happen, and that in one or two
remy> weeks, we'll be in the exact same situation
Quite the contrary. While I didn't explicitly volunteer to create the
documentation before, I'm certainly willing to work on it. (This is what I
meant by being +1 on defining a release plan and executing it.) I'll try to
start something in the next day or two.
But again, the end-user documentation isn't even my main concern. I'm not
sure we've clearly articulated to ourselves the precise scope and contract
of httpclient is and should be. And I think the interface will need a bit
of cleanup in response to that. The documentation should help us to flesh
that out quite a bit, it seems like the kind of thing we should have
agreement on before a 1.0 release, and will certainly help someone exploring
httpclient for the first time (and probably save us from a host of confused
users following a 1.0 release). Besides, all of this is much easier to
change now that at will be on the other side of that 1.0 release.
- Rod
