I'm not sure what to put this thought in reply to, so I'll just put it here: One criticism that I feel I've seen a lot, about the standard libraries of many languages, is that they are inconsistent; e.g. this sort of thing, about Java: It’s also interesting to note that Hashtable, another important standard library class, does not have any final methods. As mentioned elsewhere in this book, it’s quite obvious that some classes were designed by completely different people than others. (Notice the brevity of the method names in Hashtable compared to those in Vector.) This is precisely the sort of thing that should not be obvious to consumers of a class library. When things are inconsistent it just makes more work for the user. Yet another paean to the value of design and code walkthroughs. (from the last paragraph of http://www.codeguru.com/java/tij/tij0071.shtml) My hope is that the Haskell Platform can avoid this, and therefore that we will use a process that helps us avoid it. Thanks Ian

On 09/11/2010 01:16, Ross Paterson wrote:

On Mon, Nov 08, 2010 at 10:13:34PM +0000, Ian Lynagh wrote:

...

One criticism that I feel I've seen a lot, about the standard libraries of many languages, is that they are inconsistent; [...]

My hope is that the Haskell Platform can avoid this, and therefore that we will use a process that helps us avoid it.

That the process should address such concerns is a logical consequence of the current model of the Haskell Platform as a sort of standard, making choices on behalf of users. This model seems to be unworkable.

An alternative model would be like a Linux distribution: a selection of package versions that have been tested to work together on different platforms. Packages would have to meet the package requirements listed on the AddingPackages page (all fairly objective), but would not have to have distinct functionality or meet any other subjective criterion. The test for inclusion (or retention) would be involve weighing the number of users of the package against its maintainance cost.

That would be unlikely to produce consistency, but it seems more workable.

So the current situation is that anyone can nominate packages for inclusion in the platorm, which implies that the maintainer is not involved at all - the HP just decides whether or not to include the package in its current state. I'm wondering whether a better way to run the process is to have the maintainer more involed in the process of nomination. Instead of nominating a package for inclusion in the platform, a mainatiner would "donate" a package for inclusion. By doing so they would also be implicitly relinquishing some of the responsibilty for the design of the package to the community. This is the way I think the platform should work - it's not just a quality control on packages, but a process by which we build a sound baseline set of APIs for Haskell development. In order to do that, we need to have the community responsible for the whole of the platform, not just the entry bar. I admit that balancing the responsibilities of the maintainer with the demands of the community could be tricky. We don't want it to be a one-sided affair where the maintainer has to fix all the bugs while accommodating every demand from the community to change APIs. So presumably the expectation would be that the maintainer also devolves some of the responsibility for maintainership to the community too - there would be some benefit to being in the platform, more eyes on the code. This is moving in the opposite direction from what Ross suggests above - making the platform less of an aggregation mechanism and more of a single community project. Could it work? I'm not sure. Clearly Ross's model would "work", but it would produce something that's less like a platform. Cheers, Simon

On Tue, Nov 09, 2010 at 11:45:51AM +0000, Stephen Tetley wrote:

HOpenGL has value in the current Platform model as it can be difficult to build on certain platforms; but it is a very large work and quite domain-specific so it is not exemplary in API terms like a candidate for the Data.* or Control.* hierarchies should be.

Based on this, it sounds like rather than HOpenGL being in the platform, there should be HOpenGL binary installers for certain platforms. Perhaps cabal-install would automatically use these installers rather than building from source. Although IIRC, the arguments for including HOpenGL were that it is widely useful and its API is exemplary. Thanks Ian

On Tue, Nov 09, 2010 at 11:18:37AM +0000, Simon Marlow wrote:

I'm wondering whether a better way to run the process is to have the maintainer more involed in the process of nomination. Instead of nominating a package for inclusion in the platform, a mainatiner would "donate" a package for inclusion. By doing so they would also be implicitly relinquishing some of the responsibilty for the design of the package to the community. This is the way I think the platform should work - it's not just a quality control on packages, but a process by which we build a sound baseline set of APIs for Haskell development. In order to do that, we need to have the community responsible for the whole of the platform, not just the entry bar.

What you're describing is approximately making packages subject to the libraries submission process. (Which is what I'm doing with the transformers package currently proposed for HP.) That could work to produce consistent APIs, but I can't see it being accepted as a condition for membership of the HP. Let's do both: - a set of packages under community control that we're trying to make consistent. - a set of package versions that are popular, meet objective standards and have been tested to build together. But let's not try to force these to be the same.

On Tue, Nov 9, 2010 at 12:18 PM, Simon Marlow wrote:

I admit that balancing the responsibilities of the maintainer with the demands of the community could be tricky.  We don't want it to be a one-sided affair where the maintainer has to fix all the bugs while accommodating every demand from the community to change APIs.  So presumably the expectation would be that the maintainer also devolves some of the responsibility for maintainership to the community too - there would be some benefit to being in the platform, more eyes on the code.

Hi all, Personally I would be fine with that, providing there was a plan towards a community effort to improve the libraries we've *already approved*. To subject maintainers of candidate libraries to the "scanning tunneling electron microscope" while remaining oblivious to the huge usability/documentation problems in our grandfathered libraries --- I'm looking at you, regex-*, HTTP, old-*, QuickCheck, OpenGL, html, xhtml, pretty, etc --- isn't fair in the slightest and is going to discourage people from submitting libraries in the first place. When a library is already several standard deviations above the average quality level (like text clearly is), going over it with a fine-toothed comb and engaging in endless rounds of proposals, counter-proposals, objections, +1s, -1s, calls for consensus, etc. would be enough to cause even the most patient of people to tear their hair out. Re: improving those grandfathered libraries: I think we could probably agree that we would like every platform library to have the following properties: * continuous builds either with buildbot or something like hudson (a personal fave) * automated test suites with a high level of code coverage * haddocks for every function, with clear examples, as well as some "overview" text at the main haddock page as well as at the top of every module containing: - a description of what the library *does* - clear and complete examples showing how it is intended to be used "Check out this paper from 1997" doesn't cut it. Examples of this phenomenon are easy to find, I found these in less than a minute of searching: - http://hackage.haskell.org/packages/archive/pretty/1.0.1.1/doc/html/Text-Pre... - http://hackage.haskell.org/packages/archive/xhtml/3000.2.0.1/doc/html/Text-X... - http://hackage.haskell.org/packages/archive/syb/0.1.0.2/doc/html/Data-Generi... This is when libraries have any overview text *at all*. Examples of libraries in the platform with *no* introductory documentation are easier to find than those with good or even acceptable docs. * sane APIs without gratuitous "typeclass abstraction explosion" Maybe we should assemble a posse of volunteers, divide up the libraries, and spend a few hours each adding this kind of documentary material to try to make a real impact on the average quality level in the platform. The cynic in me, however, suspects that the willingness to do this kind of grunt work is greatly overshadowed by the appetite to engage in endless rounds of mailing list bickering. G. -- Gregory Collins

Sterling Clover wrote:

On Nov 9, 2010, at 7:02 AM, Gregory Collins wrote:

...

Hi all,

Personally I would be fine with that, providing there was a plan towards a community effort to improve the libraries we've *already approved*. To subject maintainers of candidate libraries to the "scanning tunneling electron microscope" while remaining oblivious to the huge usability/documentation problems in our grandfathered libraries --- I'm looking at you, regex-*, HTTP, old-*, QuickCheck, OpenGL, html, xhtml, pretty, etc --- isn't fair in the slightest and is going to discourage people from submitting libraries in the first place.

...

...

Maybe we should assemble a posse of volunteers, divide up the libraries, and spend a few hours each adding this kind of documentary material to try to make a real impact on the average quality level in the platform. The cynic in me, however, suspects that the willingness to do this kind of grunt work is greatly overshadowed by the appetite to engage in endless rounds of mailing list bickering.

That sounds like a great idea! A weeklong(ish?) "documentation strike force".

Step one, a good strong motivation, like here, but a bit more fleshed out, and sent to -cafe, via reddit as well, etc.

Step two, clearance from maintainers of various packages for their willingness to accept and review significant documentation patches. (I'm sure it will be forthcoming, but it should help momentum to say that authors x, y, and z all give approval and support.)

I'm the current maintainer of HTTP essentially by accident (previous maintainer dropped it, urgent changes needed for GHC compatibility), and I would like to get rid of it if anyone with more time and interest comes along. As such, I can't commit to properly reviewing documentation patches, but I would be happy to accept them without review in that case. However it seems to me that with all these grandfathered packages, the API is potentially rather more of an issue than the documentation, and updating that could be rather more disruptive and painful. Ganesh =============================================================================== Please access the attached hyperlink for an important electronic communications disclaimer: http://www.credit-suisse.com/legal/en/disclaimer_email_ib.html ===============================================================================

On 11/9/10 7:02 AM, Gregory Collins wrote:

Maybe we should assemble a posse of volunteers, divide up the libraries, and spend a few hours each adding this kind of documentary material to try to make a real impact on the average quality level in the platform.

Perhaps we could make use of the haskellers.com SIG model to set this up and popularize it.

The cynic in me, however, suspects that the willingness to do this kind of grunt work is greatly overshadowed by the appetite to engage in endless rounds of mailing list bickering.

Methinks going with a SIG (with an associated hackathon) would help overcome the intertia. Because, really, that's what it is. With large community projects I've found that whatever the level of documentation and testing is, people tend to roll along with it (with some energy lost to friction :) Which means that things only really become a problem when there gets to be little/no documentation. Bodies at rest; bodies in motion. Certainly I've felt that packages like containers are effectively static rather than under _active_ maintenance and open to user contributions (the recent optimizations being the exception to prove the rule). -- Live well, ~wren

On Tue, Nov 09, 2010 at 11:18:37AM +0000, Simon Marlow wrote:

This is moving in the opposite direction from what Ross suggests above - making the platform less of an aggregation mechanism and more of a single community project. Could it work? I'm not sure. Clearly Ross's model would "work", but it would produce something that's less like a platform.

Steering committee, I think we need to resolve this question before we can make progress. How should we proceed? Also, is there a better list than haskell-platform@projects for communicating with the steering committee? I don't see any addresses on the committee list page: http://trac.haskell.org/haskell-platform/wiki/Members By the way, I see Don Stewart is now listed as a steering committee member; was that announced somewhere? Thanks Ian

igloo:

On Tue, Nov 09, 2010 at 11:18:37AM +0000, Simon Marlow wrote:

...

This is moving in the opposite direction from what Ross suggests above - making the platform less of an aggregation mechanism and more of a single community project. Could it work? I'm not sure. Clearly Ross's model would "work", but it would produce something that's less like a platform.

Steering committee, I think we need to resolve this question before we can make progress. How should we proceed?

Also, is there a better list than haskell-platform@projects for communicating with the steering committee? I don't see any addresses on the committee list page: http://trac.haskell.org/haskell-platform/wiki/Members

What is the question? I don't think libraries@ has a mandate to change the current HP goals or process, for example, so I'm unclear what exactly is being proposed. -- Don

igloo:

...

...

Steering committee, I think we need to resolve this question before we can make progress. How should we proceed?

What is the question?

Should the HP attempt to provide:

A set of packages that are popular and meet certain quality standards

or:

A set of packages that are popular, meet certain quality standards and have a consistent API

?

...

I don't think libraries@ has a mandate to change the current HP goals

Surely someone must have a mandate to change them?

It was unclear to me what goals of the HP were being suggested to change. It appears that the mission of the HP is not in question here, which was my concern.

Also, what is the current goal? I thought it was the second one, but I don't know whether or not I am in a minority.

The goals are, as stated in the original position statement by me and Duncan: "a complete Haskell development environment, batteries included." More specifically (from "Haskell: Batteries Included"), the project should produce: * high quality libraries. * commonly-needed functionality * convenient packaging for many operating systems * a set of clear criteria for when packages are accepted So this proposal would be to determine to what extent a "consistent API" is one of the criteria. Now, "consistent APIs" seems desirable, although maintainers have full rights to modify the APIs as they see fit, as long as they follow the PVP (once their package is included). That suggests to me that we may only recommend APIs guidelines -- not require them. -- Don

On 11 November 2010 16:21, Ian Lynagh wrote:

Also, is there a better list than haskell-platform@projects for communicating with the steering committee? I don't see any addresses on the committee list page:    http://trac.haskell.org/haskell-platform/wiki/Members

We could do with setting up some sensible email alias for the group. Perhaps you can help us with that Ian. Re the idea of a committee chair, I'm happy to suggest that to the committee. Duncan

On 11/12/10 18:57, Ian Lynagh wrote:

On Thu, Nov 11, 2010 at 10:15:46PM +0000, Duncan Coutts wrote:

...

On 11 November 2010 16:21, Ian Lynagh wrote:

...

Also, is there a better list than haskell-platform@projects for communicating with the steering committee? I don't see any addresses on the committee list page: http://trac.haskell.org/haskell-platform/wiki/Members

We could do with setting up some sensible email alias for the group. Perhaps you can help us with that Ian.

This should go to the steering committee now: haskell-platform@community.haskell.org

Is mail that goes to that address publicly archived? If not, it should be an intentional choice, not accidental (I currently lean towards everything public/archived by default). -Isaac

On 11/8/10 10:04 AM, Duncan Coutts wrote:

On 8 November 2010 08:06, Bryan O'Sullivan wrote:

...

An Apache-style vote system for resolving points of disagreement, so that we can move past them reasonably swiftly instead of going in endless morale-sapping circles. This is particularly important to me. I'd really have liked to be able to say "we discussed this, it's over" about naming, but instead I feel that objectors held, in effect, a veto. The current consensus system seems to require complete agreement from all parties, which seems perverse.

I'll raise this with the steering committee. Voting is something we tried to avoid in the process when we first designed it, but the intention was always to see how things went and review. Voting may be a useful thing to bring in at some points if there's a clear case that some decision is better than no decision. If we decide to add this to the process my view would be that it should be only used occasionally for specific issues, perhaps issues of general principle rather than specific issues in a proposal (obviously Text brought up a couple of those).

I don't know much about Apache's system, but I think it would be good to have something like this considered as an informal show of hands, rather than as voting per se. (Perhaps my idea belongs more to the previous bullet point than this one.) There are good reasons to want to avoid voting, but I think a good deal of the repetition in discussing things was due to a lack of some more permanent means of people just specifying how they feel about some given topic. -- Live well, ~wren

On 11/11/10 11:08, Ian Lynagh wrote:

On Mon, Nov 08, 2010 at 03:04:29PM +0000, Duncan Coutts wrote:

...

and to stop us all from hiding behind "oh I thought you were going to do it" and "ah sorry I've been a bit busy".

Someone asked me the other day what the role of the haskell.org committee chair is, and it struck me that what I see as the chair's roles (making sure things keep moving, and ensuring that all issues raised get resolved) are what was missing from the HP steering committee.

What you've proposed is essentially that each addition proposal gets its own chair, and maybe that is enough, but I wonder if the HP SC should have a general chair too. The chair would ensure that someone realises that they're responsible for a particular issue, perhaps encourage people to make more proposals, start discussions like the Great Licence Debate, and so on.

Yes, I think we should at least have a dispatcher who notices when a discussion is starting that needs a committee-member assigned to it, and enlists a committee-member (normally the next person on the queue). I'm indifferent whether the same person gets more responsibilities (it may depend on whether someone wants to volunteer to do that outreach). -Isaac