Personal tools

Library submissions

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
m (minor: add a helpful link to the validation process)
 
(37 intermediate revisions by 9 users not shown)
Line 1: Line 1:
This page describes the process for maintaining the  
+
This page describes the process followed by the [http://www.haskell.org/haskellwiki/Core_Libraries_Committee Core Libraries Committee], or CLC, for maintaining the libraries it oversees. Many of these libraries are '''core libraries''', defined as libraries which ship with GHC itself, which is the source of the name for this committee. However, over the years, other libraries have been subsumed under CLC maintainership.
'''Core libraries'''.  The core libraries are a subset of the packages in the
+
Haskell Platform, and define basic APIs that are expected to be
+
available in any Haskell implementation. They are listed under "The Core Libraries" below.
+
  
Non-core libraries are, of course, managed by their own authors/maintainers (named in their .cabal file), using whatever policies those maintainers see fit. [Note: arguably the policies below might usefully be applied to all libraries embodied in the Haskell Platform, but that is a question for the HP team.]
+
Generally speaking, all libraries maintained by the CLC are "important" for some reason or another. The core libraries themselves are particularly important since they ship with GHC, and are generally used by a large subset of the community (e.g., base is used by virtually all Haskell code).
  
= General principles =
+
= Goals =
  
* Each core package has a named maintainer, or small group of maintainers, who have commit access to the package.
+
Our goals for maintenance of these libraries are:
  
* Third parties are encouraged to make proposals for changes, both to the library API and its implementation, by sending the proposal to the maintainer (CC'ing the libraries mailing list).
+
* Bugs are resolved
 +
* Feature requests can be implemented
 +
* Patches can be merged
 +
* All of this is done in such a way as to avoid creating problems for users of these libraries
  
* The maintainer is trusted to decide what changes to make to the package, and when. They are strongly encouraged to follow the guidance below, but the general principle is: the community offers opinions, but the maintainers decide.
+
The last point is vital. These libraries must have the highest quality
 +
standards of any libraries in the Haskell ecosystem. In order to ensure timely
 +
response to issues (the first three points) while maintaining the quality
 +
standards of the fourth point, we have a dual maintainership system in place.
  
 +
Each library has an individual maintainer for routine maintenance of the
 +
package. In addition, the
 +
[http://www.haskell.org/haskellwiki/Core_Libraries_Committee Core Libraries Committee], or CLC, has oversight on the maintenance of these libraries.
  
= Responsiveness =
+
The individual maintainer is responsible for dealing with each individual issue
 +
against that library. That individual is fully empowered to make decisions on
 +
that library. However, the following restrictions apply:
  
* Third parties submitting proposals to the maintainer of a library can expect a timely and thoughtful response.
+
* For "controversial" decisions (definition discussed below), the maintainer should not make a unilateral decision, but rather discuss with the CLC as a whole (and possibly a wider audience)
* The more effort the proposer invests (for example, by constructing a patch rather than making an off-the-cuff suggestion) the more consideration s/he can reasonably expect.
+
* If the CLC is dissatisfied with the job being performed by the maintainer, it may remove the maintainer from his/her role (via a majority vote)
* Proposals that have widespread support, and are accompanied by patches (preferably with tests and documentation), should normally be accepted by the maintainer. 
+
* It is up to the maintainer to decide what "widespread" means; in particular, it does not always mean "a majority of those who responded".  The majority-responder story is vulnerable to selection bias; e.g. 7 people (out of a client base of hundreds) say "add this function" but the maintainer thinks it will make the interface incrementally more complicated without sufficient benefit.
+
* Where there is significant work involved in implementing a proposal, it is reasonable for a maintainer to ask for a patch.  The principle is that maintainers are not obliged to do the work of implementing a proposal, even if it does enjoy wide support.  For more substantial changes, it makes sense to develop the implementation in dialogue with the maintainer.
+
  
= Guidance for proposers =
+
'''NOTE''': The oversight role of the CLC only applies to libraries which have explicitly been placed under the CLC's maintainership. Other libraries are encouraged to follow this practice, but are not required to do so. Currently, the libraries which are not maintained by the CLC are containers, parallel, pretty, time, and xhtml.
  
A "proposal" can be anything from a one-sentence suggestion to a fully-implemented, tested, and documented patch.
+
The list of all libraries is provided below.
However, the more substantial the proposal the more attention you can expect.  The process is this:
+
  
* Send your proposal by email to the maintainer, with a copy to the libraries@haskell.org mailing list (which you need to [http://www.haskell.org/mailman/listinfo/libraries subscribe] to before posting).
+
While this page only covers maintenance of CLC-maintained libraries, the policies
 +
described may be useful for other libraries, especially for packages
 +
in the Haskell Platform.
  
* Set a deadline for discussion (no less than two weeks), and act as chair/moderator for the discussion.
+
= The Libraries =
  
* At the end of the discussion period, summarise your understanding of the consensus (or lack thereof), including a link to the thread in the mailing list archives, and send the summary to the maintainer for decision. The deadline gives you a moment to summarise the debate and hand over to the maintainer. It isn't a deadline for the maintainer to decide; for example he or she may seek more discussion first.
+
Our definition of "core library" is a library that ships with GHC. This can happen for one of three reasons:
  
* If the decision is positive, [http://hackage.haskell.org/trac/ghc/newticket create a ticket] on the GHC trac. The description of the ticket can summarise the proposal and link to the mail thread. Further discussion and implementation patches can be attached to the ticket, and the ticket helps the maintainer to keep track of what is on the go.  (Obviously if the maintainer prefers some other mechanism, follow his or her guidance.)
+
# It is part of the Haskell language standard
 +
# It is tightly coupled to GHC’s implementation of some feature. These libraries cannot be changed independently of GHC. You could think of them as part of GHC, part that happens to be implemented in library code.
 +
# It is used to build GHC itself. We have to ship these libraries with GHC because ghc itself is a package, and so we must have installed packages for anything the ghc package depends on.
  
* For non-trivial changes the maintainer may ask for a patch.  You may create the patch up front, and make it part of your proposal; or you may want to have some discussion about the design first, and only then roll up your sleeves to do the implementation; and for bigger jobs you may want to wait until the maintainer agrees in principle with the change.
+
The following table lists the libraries maintained by the CLC, their primary maintainers, issue tracker for filing bugs and feature requests, and the reason the library is a member of the core libraries (one of the three reasons above, or blank if the library is a non-core library). Ideally, all libraries listed will have a maintainer as well, though we have not filled all roles yet.
 
+
Here are desirable properties for a proposal and its implementation.  The more of these properties your proposal or patch has, the more likely it is that the maintainer will adopt your idea.  After all, to adopt it the maintainter will have to do whatever tasks you didn't do.
+
 
+
* '''Description'''.  A good proposal says clearly ''what'' you propose, ''why'' it is a good idea, and what its consequences would be.
+
* '''Patch'''.  Use <tt>darcs record</tt> or <tt>git commit</tt> (depending on what sort of repo the library lives in) to create it. Save the patch to a file, using <tt>darcs send --output</tt> or <tt>git format-patch</tt>. Make your changes against a copy of the master branch of the  relevant library, and make sure it compiles.
+
* '''Portability'''. Good code is portable. In particular, try to ensure the code runs in Hugs and GHC, and on Windows and Linux.
+
* '''Style'''. Good code follows the conventions in the library you are modifying.
+
* '''Documentation'''. Good code includes valid [http://haskell.org/haddock Haddock] documentation.
+
* '''Tests'''. Good patches have suitable tests for the library's testsuite.
+
 
+
= Guidance for maintainers =
+
 
+
The principle is that we '''trust the maintainer''' to behave sensibly.  The guidelines below are just that: guidelines, not rules.  Still, the  core libraries are used by many, many people, so maintainers should make every effort not to mess them up by accident. 
+
 
+
* '''API changes should be discussed''' on the libraries mailing list prior to making the change, even if the maintainer is the proposer.  The maintainer still has ultimate say in what changes are made, but the community should have the opportunity to comment on changes. However, unanimity (or even a majority) is not required.
+
 
+
* '''Every API change should be described precisely in the commit log.'''  The commit logs should be sent to a public mailing list, or otherwise made easily available (e.g. via github), so that the community can keep an eye on changes and comment.
+
 
+
* '''Backwards compatibility''' is important to many users.  API changes are expected to retain backwards compatibility wherever possible.  However, from time to time we may decide to have major revisions which are explicitly not backwards compatible; in these cases we may try to make the previous version of the package available concurrently, as in the base-3/base-4 switchover.
+
 
+
* You don't need to consult the community for '''purely internal changes'''; i.e. changes that do not affect the library's clients.
+
 
+
* Changes that simply '''widen the API by adding new functions''' are a bit of a grey area.  It's better to consult the community, because there may be useful feedback about (say) the order of arguments, or the name of the function, or whatnot.  On the other hand few clients will actually break if you add a new function to the API. Use your judgment.
+
 
+
Libraries maintained by the GHC team are subject to the GHC validation policy - patches will be tested for validation before committing ([http://hackage.haskell.org/trac/ghc/wiki/TestingPatches TestingPatches]).  Those packages not maintained by the GHC team will probably have a GHC lagging mirror repository that is subject to validation.
+
 
+
= The Core Libraries =
+
 
+
The following packages constitute the core libraries:
+
  
 
{| border="1"
 
{| border="1"
! Package !! Maintainer
+
! Package !! Maintainer !! Issue Tracker !! Reason
 
|-
 
|-
| [http://hackage.haskell.org/package/array array] || GHC HQ
+
| [http://hackage.haskell.org/package/array array] || Dan Doel || [https://ghc.haskell.org/trac/ghc/newticket?component=libraries%20%28other%29&keywords=array GHC Trac] || 1, 3
 
|-
 
|-
| [http://hackage.haskell.org/package/base base] || GHC HQ
+
| [http://hackage.haskell.org/package/base base] || Edward Kmett || [https://ghc.haskell.org/trac/ghc/newticket?component=libraries%20%28base GHC Trac] || 1, and partly 2
 
|-
 
|-
| [http://hackage.haskell.org/package/containers containers] || Johan Tibell and Milan Straka
+
| [http://hackage.haskell.org/package/deepseq deepseq] || Herbert Valerio Riedel || [https://github.com/haskell/deepseq/issues Github] || 3
 
|-
 
|-
| [http://hackage.haskell.org/package/deepseq deepseq] || Simon Marlow
+
| [http://hackage.haskell.org/package/directory directory] || Phil Ruffwind and Elliot Robinson|| [https://github.com/haskell/directory/issues Github] || 3
 
|-
 
|-
| [http://hackage.haskell.org/package/directory directory] || GHC HQ
+
| [http://hackage.haskell.org/package/filepath filepath] || Neil Mitchell || [https://github.com/haskell/filepath/issues Github] || 3
 
|-
 
|-
| [http://hackage.haskell.org/package/extensible-exceptions extensible-exceptions] || GHC HQ  
+
| [http://hackage.haskell.org/package/ghc-prim ghc-prim] || GHC HQ || [http://ghc.haskell.org/trac/ghc/newticket?component=libraries%20%28other%29&keywords=ghc-prim GHC Trac] || 2
 
|-
 
|-
| [http://hackage.haskell.org/package/ghc-prim ghc-prim] || GHC HQ  
+
| [http://hackage.haskell.org/package/hpc hpc] || GHC HQ || [http://ghc.haskell.org/trac/ghc/newticket?component=Code%20Coverage GHC Trac] || 2
 
|-
 
|-
| [http://hackage.haskell.org/package/hpc hpc] || Andy Gill
+
| [http://hackage.haskell.org/package/mtl mtl] || Edward Kmett || [https://github.com/ekmett/mtl/issues Github] || non-core
 
|-
 
|-
| [http://hackage.haskell.org/package/mtl mtl] || Edward Kmett
+
| [http://hackage.haskell.org/package/primitive primitive] || Dan Doel || [https://github.com/haskell/primitive/issues Github] || non-core
 
|-
 
|-
| [http://hackage.haskell.org/package/parallel parallel] || Simon Marlow
+
| [http://hackage.haskell.org/package/process process] || Michael Snoyman || [https://github.com/haskell/process/issues Github] || 3
 
|-
 
|-
| [http://hackage.haskell.org/package/pretty pretty] || David Terei
+
| [http://hackage.haskell.org/package/random random] || Dominic Steinitz and Carter Schonwald || [https://github.com/haskell/random/issues Github] || non-core
 
|-
 
|-
| [http://hackage.haskell.org/package/process process] || GHC HQ  
+
| [http://hackage.haskell.org/package/stm stm] || GHC HQ || [https://ghc.haskell.org/trac/ghc/newticket?component=libraries%20%28other%29&keywords=stm GHC Trac] || 2
 
|-
 
|-
| [http://hackage.haskell.org/package/random random] || Ryan Newton
+
| [http://hackage.haskell.org/package/template-haskell template-haskell] || Edward Kmett || [http://ghc.haskell.org/trac/ghc/newticket?component=Template%20Haskell GHC Trac] || 2
 
|-
 
|-
| [http://hackage.haskell.org/package/template-haskell template-haskell] || GHC HQ
+
| [http://hackage.haskell.org/package/unix unix] || TBD || [https://github.com/haskell/unix/issues Github] || 3
 
|-
 
|-
| [http://hackage.haskell.org/package/unix unix] || GHC HQ
+
| [http://hackage.haskell.org/package/vector vector] || Dan Doel || [https://github.com/haskell/vector/issues Github] || non-core
 
|-
 
|-
| [http://hackage.haskell.org/package/Win32 Win32] || Bryan O'Sullivan
+
| [http://hackage.haskell.org/package/old-locale old-locale] || TBD || [https://github.com/haskell/old-locale/issues Github] || non-core
 +
|-
 +
| [http://hackage.haskell.org/package/old-time old-time] || TBD || [https://github.com/haskell/old-time/issues Github] || non-core
 +
|-
 +
| [http://hackage.haskell.org/package/Win32 Win32] || [https://ghc.haskell.org/trac/ghc/wiki/WindowsTaskForce Windows Task Force] || [https://github.com/haskell/win32/issues Github] || 3
 
|-
 
|-
| [http://hackage.haskell.org/package/xhtml xhtml] || Chris Dornan
 
 
|}
 
|}
  
The maintainer "GHC HQ" means Simon Marlow, Simon Peyton Jones, and Ian Lynagh.  Daniel Fischer has taken responsibility for numeric stuff. Email cvs-ghc@haskell.org
+
The maintainer "GHC HQ" means Simon Marlow, Simon Peyton Jones, and Ian Lynagh.  Daniel Fischer has taken responsibility for numeric stuff. Email ghc-devs@haskell.org
 +
 
 +
The [http://www.haskell.org/haskellwiki/Core_Libraries_Committee Core Libraries Committee] was formed to provide a maintainer of many of the packages previously managed by GHC HQ and can be reached by emailing core-libraries-committee@haskell.org or publicly through libraries@haskell.org.
 +
 
 +
There is no requirement that a library maintainer be him/herself a member of the CLC.
 +
 
 +
If you believe an additional library should be part of the CLC library set, or
 +
wish to take over as maintainer on one of the libraries above, please send an
 +
email to the libraries@ mailing list with the request.
  
 
The following packages match the appropriate language standard, and as such cannot change independently.  The code is maintained by the GHC team.
 
The following packages match the appropriate language standard, and as such cannot change independently.  The code is maintained by the GHC team.
Line 116: Line 106:
 
|}
 
|}
  
These packages are maintained only for backward compatibility, and are not expected to undergo API changes in the future.  
+
The following packages are core libraries in that they ship with GHC, but are not maintained by the core libraries committee.
  
 
{| border="1"
 
{| border="1"
 +
! Package !! Maintainer !! Issue Tracker !! Reason
 
|-
 
|-
| [http://hackage.haskell.org/package/old-locale old-locale] || GHC HQ
+
| [http://hackage.haskell.org/package/containers containers] || Edward Kmett and David Feuer || [https://github.com/haskell/containers/issues Github] || 3
 +
|-
 +
| [http://hackage.haskell.org/package/hoopl hoopl] || Ning Wang || [https://github.com/haskell/hoopl/issues Github] || 3
 +
|-
 +
| [http://hackage.haskell.org/package/parallel parallel] || Simon Marlow || [https://github.com/haskell/parallel/issues Github] || non-core ('''NOTE''': Should we remove this library from the table?)
 +
|-
 +
| [http://hackage.haskell.org/package/pretty pretty] || David Terei || [https://github.com/haskell/pretty/issues Github] || 3
 +
|-
 +
| [http://hackage.haskell.org/package/time time] || Ashley Yakeley || [https://github.com/haskell/time/issues Github] || 3
 +
|-
 +
| [http://hackage.haskell.org/package/xhtml xhtml] || Chris Dornan || [https://github.com/haskell/xhtml/issues Github] || 3
 
|-
 
|-
| [http://hackage.haskell.org/package/old-time old-time]  || GHC HQ
 
 
|}
 
|}
 +
 +
= General workflow =
 +
 +
# Issues should be filed against the appropriate issue tracker for that library.
 +
#* Note: In the past, core library issues were all made against GHC Trac. That is no longer the case, and issues opened in such a way will likely be closed with a request to reopen in the appropriate place.
 +
# If any member of the committee feels particularly interested or well qualified in an individual issue, and the official maintainer has not started working on the issue yet, he/she should feel free to self-assign the issue. Similarly, if the official maintainer feels unqualified to handle an issue, he/she should assign to another individual (whether part of the CLC or not).
 +
# There must be a clear status for issues at all time, and this status should be understandable from the Trac discussion itself. Side channels of communication must be recorded in Trac (or at least referenced from there). The community should be able to read a discussion, understand current status, and also have a clear idea of how to move the ticket forward towards resolution. (Note that this requirement is very similar to [https://github.com/commercialhaskell/commercialhaskell/blob/master/guide/maintainer-communication.md the commercial SIG maintainer communication guide].)
 +
# Any individual should feel empowered to assign unassigned or misassigned issues to the appropriate maintainer.
 +
# Ultimately, it is the responsibility of the committee chair to ensure that this process is continuing to run, and that issues are being addressed and resolved quickly and professionally. The chair may of course employ the assistance of others in this endeavor.
 +
 +
Since this has been a difficult point in the past, is bears repeating: '''an individual maintainer is fully empowered to make decisions, and should do so!''' Only controversial decisions should involve the rest of the CLC.
 +
 +
= Responsiveness =
 +
 +
* Third parties submitting proposals to the maintainer of a library can expect a timely and thoughtful response.
 +
* The more effort the proposer invests (for example, by constructing a patch rather than making an off-the-cuff suggestion) the more consideration s/he can reasonably expect.
 +
* Ideally, no issues will be left without a response for more than one week, with two weeks being a maximum. If a maintainer will be on vacation or otherwise unavailable, he/she should notify the rest of the committee beforehand.
 +
* If there is more than a week's delay on an issue from the maintainer's side, it is acceptable to ping him/her.
 +
* If there is more than a week's delay on an issue from the issue creator's side, the maintainer should feel free to close the issue if desired, with a comment explaining why it was closed.
 +
* Proposals that have widespread support, and are accompanied by patches (preferably with tests and documentation), should normally be accepted by the maintainer. 
 +
* It is up to the maintainer to decide what "widespread" means; in particular, it does not always mean "a majority of those who responded".  The majority-responder story is vulnerable to selection bias; e.g. 7 people (out of a client base of hundreds) say "add this function" but the maintainer thinks it will make the interface incrementally more complicated without sufficient benefit.
 +
* Where there is significant work involved in implementing a proposal, it is reasonable for a maintainer to ask for a patch.  The principle is that maintainers are not obliged to do the work of implementing a proposal, even if it does enjoy wide support.  For more substantial changes, it makes sense to develop the implementation in dialogue with the maintainer.
 +
 +
= Mistakes =
 +
 +
People are fallible. The process above will allow some mistakes to be made.
 +
That's a conscious trade-off we're accepting now. If we had unlimited time and
 +
unlimited manpower, we may decide to discuss in detail each and every issue.
 +
However, that's not our reality: everyone involved has other responsibilities
 +
and does not have time or inclination to discuss in depth each issue.
 +
 +
Said another way: let's make progress with 95% accuracy rather than get bogged
 +
down in gridlock with 99% accuracy.
 +
 +
= Controversial decisions =
 +
 +
It's impossible in this document to record all possible forms of a
 +
controversial decision. Here are some basic guidelines:
 +
 +
* Adding a new, useful function under a clear name is probably not controversial
 +
* Breaking the API in any way is almost certainly controversial
 +
* Changing the semantics of an existing function is almost certainly controversial
 +
* Changes affecting Prelude and the Haskell Report are almost certainly controversial
 +
 +
It is important that, at the very least, the CLC receives an email on this
 +
topic. The individual maintainer is still in charge of the issue, but should
 +
give the CLC a chance to express an opinion. If after a reasonable amount of
 +
time (let's say one week) no objections are raised, the maintainer should feel
 +
free to move ahead with the change.
 +
 +
The CLC should repeat this decision making process again with more
 +
controversial issues. The prime example of this was the "burning bridges
 +
proposal": a change which drastically impacts <code>Prelude</code> should
 +
almost certainly be elevated to the libraries@ mailing list. Anything going to
 +
libraries@ should have at least a two week deadline on it.
 +
 +
At the end of the day, the CLC is still the body with decision making power.
 +
Explicitly: no single person should ever have veto power on a change. That
 +
includes the library maintainer; if the CLC votes against the library
 +
maintainer, that decision will stand. The CLC may itself decide to request
 +
support from others to make a decision, but is never required to do so.
 +
 +
= Guide to proposers =
 +
 +
Previously (before February 2015), the initiative remained with the proposer
 +
for quite a while on the proposal process. The process described here is
 +
significantly different, so please note the change.
 +
 +
All library proposals should start on the relevant issue tracker. This may be a
 +
bug report, feature request, or even a complete patch/pull request. At this
 +
point, the library maintainer is responsible for taking next steps. Some
 +
example next steps would be to accept the patch, implement a bug fix, reject a
 +
feature request, or decide that this is a controversial decision that must be
 +
discussed with the CLC.
 +
 +
If the CLC decides that the discussion must be discussed with the libraries@
 +
mailing list, the original proposer may be asked to moderate the libraries@
 +
mailing list discussion. The general format for this is:
 +
 +
* Send your proposal by email to the libraries@haskell.org mailing list (which you need to [http://www.haskell.org/mailman/listinfo/libraries subscribe] to before posting).
 +
 +
* Set a deadline for discussion (no less than two weeks), and act as chair/moderator for the discussion.
 +
 +
* Following discussion, it's the responsibility of the core libraries committee to determine if the proposal should be accepted. Send an email to the core libraries committee requesting a decision, optionally including your own summary of the mailing list discussion.
 +
 +
* From that point forward, the CLC and maintainer will again be responsible for making a decision on how to proceed, and will inform the proposer and the mailing list. Possible decisions include acceptance, rejection, and requesting a patch be provided.
 +
 +
Here are desirable properties for a proposal and its implementation.  The more of these properties your proposal or patch has, the more likely it is that the maintainer will adopt your idea.  After all, to adopt it the maintainter will have to do whatever tasks you didn't do.
 +
 +
* '''Description'''.  A good proposal says clearly ''what'' you propose, ''why'' it is a good idea, and what its consequences would be.
 +
* '''Patch'''.  Use <tt>darcs record</tt> or <tt>git commit</tt> (depending on what sort of repo the library lives in) to create it. Save the patch to a file, using <tt>darcs send --output</tt> or <tt>git format-patch</tt>. Make your changes against a copy of the master branch of the  relevant library, and make sure it compiles.
 +
* '''Portability'''. Good code is portable. In particular, try to ensure the code runs in Hugs and GHC, and on Windows and Linux.
 +
* '''Style'''. Good code follows the conventions in the library you are modifying.
 +
* '''Documentation'''. Good code includes valid [http://haskell.org/haddock Haddock] documentation.
 +
* '''Tests'''. Good patches have suitable tests for the library's testsuite.
 +
 +
= Guidance for maintainers =
 +
 +
The principle is that we '''trust the maintainer''' to behave sensibly.  The guidelines below are just that: guidelines, not rules.  Still, the  core libraries are used by many, many people, so maintainers should make every effort not to mess them up by accident. 
 +
 +
* '''API changes should be discussed''' on the libraries mailing list prior to making the change, even if the maintainer is the proposer.  The maintainer still has ultimate say in what changes are made, but the community should have the opportunity to comment on changes. However, unanimity (or even a majority) is not required.
 +
 +
* '''Every API change should be described precisely in the commit log.'''  The commit logs should be sent to a public mailing list, or otherwise made easily available (e.g. via github), so that the community can keep an eye on changes and comment.
 +
 +
* '''Backwards compatibility''' is important to many users.  API changes are expected to retain backwards compatibility wherever possible.  However, from time to time we may decide to have major revisions which are explicitly not backwards compatible; in these cases we may try to make the previous version of the package available concurrently, as in the base-3/base-4 switchover.
 +
 +
* You don't need to consult the community for '''purely internal changes'''; i.e. changes that do not affect the library's clients.
 +
 +
* Changes that simply '''widen the API by adding new functions''' are a bit of a grey area.  It's better to consult the community, because there may be useful feedback about (say) the order of arguments, or the name of the function, or whatnot.  On the other hand few clients will actually break if you add a new function to the API. Use your judgment.
 +
 +
Libraries maintained by the GHC team are subject to the GHC validation policy - patches will be tested for validation before committing ([http://hackage.haskell.org/trac/ghc/wiki/TestingPatches TestingPatches]).  Those packages not maintained by the GHC team will probably have a GHC lagging mirror repository that is subject to validation.
  
 
= See also =
 
= See also =

Latest revision as of 13:36, 13 April 2016

This page describes the process followed by the Core Libraries Committee, or CLC, for maintaining the libraries it oversees. Many of these libraries are core libraries, defined as libraries which ship with GHC itself, which is the source of the name for this committee. However, over the years, other libraries have been subsumed under CLC maintainership.

Generally speaking, all libraries maintained by the CLC are "important" for some reason or another. The core libraries themselves are particularly important since they ship with GHC, and are generally used by a large subset of the community (e.g., base is used by virtually all Haskell code).

Contents

[edit] 1 Goals

Our goals for maintenance of these libraries are:

  • Bugs are resolved
  • Feature requests can be implemented
  • Patches can be merged
  • All of this is done in such a way as to avoid creating problems for users of these libraries

The last point is vital. These libraries must have the highest quality standards of any libraries in the Haskell ecosystem. In order to ensure timely response to issues (the first three points) while maintaining the quality standards of the fourth point, we have a dual maintainership system in place.

Each library has an individual maintainer for routine maintenance of the package. In addition, the Core Libraries Committee, or CLC, has oversight on the maintenance of these libraries.

The individual maintainer is responsible for dealing with each individual issue against that library. That individual is fully empowered to make decisions on that library. However, the following restrictions apply:

  • For "controversial" decisions (definition discussed below), the maintainer should not make a unilateral decision, but rather discuss with the CLC as a whole (and possibly a wider audience)
  • If the CLC is dissatisfied with the job being performed by the maintainer, it may remove the maintainer from his/her role (via a majority vote)

NOTE: The oversight role of the CLC only applies to libraries which have explicitly been placed under the CLC's maintainership. Other libraries are encouraged to follow this practice, but are not required to do so. Currently, the libraries which are not maintained by the CLC are containers, parallel, pretty, time, and xhtml.

The list of all libraries is provided below.

While this page only covers maintenance of CLC-maintained libraries, the policies described may be useful for other libraries, especially for packages in the Haskell Platform.

[edit] 2 The Libraries

Our definition of "core library" is a library that ships with GHC. This can happen for one of three reasons:

  1. It is part of the Haskell language standard
  2. It is tightly coupled to GHC’s implementation of some feature. These libraries cannot be changed independently of GHC. You could think of them as part of GHC, part that happens to be implemented in library code.
  3. It is used to build GHC itself. We have to ship these libraries with GHC because ghc itself is a package, and so we must have installed packages for anything the ghc package depends on.

The following table lists the libraries maintained by the CLC, their primary maintainers, issue tracker for filing bugs and feature requests, and the reason the library is a member of the core libraries (one of the three reasons above, or blank if the library is a non-core library). Ideally, all libraries listed will have a maintainer as well, though we have not filled all roles yet.

Package Maintainer Issue Tracker Reason
array Dan Doel GHC Trac 1, 3
base Edward Kmett GHC Trac 1, and partly 2
deepseq Herbert Valerio Riedel Github 3
directory Phil Ruffwind and Elliot Robinson Github 3
filepath Neil Mitchell Github 3
ghc-prim GHC HQ GHC Trac 2
hpc GHC HQ GHC Trac 2
mtl Edward Kmett Github non-core
primitive Dan Doel Github non-core
process Michael Snoyman Github 3
random Dominic Steinitz and Carter Schonwald Github non-core
stm GHC HQ GHC Trac 2
template-haskell Edward Kmett GHC Trac 2
unix TBD Github 3
vector Dan Doel Github non-core
old-locale TBD Github non-core
old-time TBD Github non-core
Win32 Windows Task Force Github 3

The maintainer "GHC HQ" means Simon Marlow, Simon Peyton Jones, and Ian Lynagh. Daniel Fischer has taken responsibility for numeric stuff. Email ghc-devs@haskell.org

The Core Libraries Committee was formed to provide a maintainer of many of the packages previously managed by GHC HQ and can be reached by emailing core-libraries-committee@haskell.org or publicly through libraries@haskell.org.

There is no requirement that a library maintainer be him/herself a member of the CLC.

If you believe an additional library should be part of the CLC library set, or wish to take over as maintainer on one of the libraries above, please send an email to the libraries@ mailing list with the request.

The following packages match the appropriate language standard, and as such cannot change independently. The code is maintained by the GHC team.

haskell2010 GHC HQ
haskell98 GHC HQ

The following packages are core libraries in that they ship with GHC, but are not maintained by the core libraries committee.

Package Maintainer Issue Tracker Reason
containers Edward Kmett and David Feuer Github 3
hoopl Ning Wang Github 3
parallel Simon Marlow Github non-core (NOTE: Should we remove this library from the table?)
pretty David Terei Github 3
time Ashley Yakeley Github 3
xhtml Chris Dornan Github 3

[edit] 3 General workflow

  1. Issues should be filed against the appropriate issue tracker for that library.
    • Note: In the past, core library issues were all made against GHC Trac. That is no longer the case, and issues opened in such a way will likely be closed with a request to reopen in the appropriate place.
  2. If any member of the committee feels particularly interested or well qualified in an individual issue, and the official maintainer has not started working on the issue yet, he/she should feel free to self-assign the issue. Similarly, if the official maintainer feels unqualified to handle an issue, he/she should assign to another individual (whether part of the CLC or not).
  3. There must be a clear status for issues at all time, and this status should be understandable from the Trac discussion itself. Side channels of communication must be recorded in Trac (or at least referenced from there). The community should be able to read a discussion, understand current status, and also have a clear idea of how to move the ticket forward towards resolution. (Note that this requirement is very similar to the commercial SIG maintainer communication guide.)
  4. Any individual should feel empowered to assign unassigned or misassigned issues to the appropriate maintainer.
  5. Ultimately, it is the responsibility of the committee chair to ensure that this process is continuing to run, and that issues are being addressed and resolved quickly and professionally. The chair may of course employ the assistance of others in this endeavor.

Since this has been a difficult point in the past, is bears repeating: an individual maintainer is fully empowered to make decisions, and should do so! Only controversial decisions should involve the rest of the CLC.

[edit] 4 Responsiveness

  • Third parties submitting proposals to the maintainer of a library can expect a timely and thoughtful response.
  • The more effort the proposer invests (for example, by constructing a patch rather than making an off-the-cuff suggestion) the more consideration s/he can reasonably expect.
  • Ideally, no issues will be left without a response for more than one week, with two weeks being a maximum. If a maintainer will be on vacation or otherwise unavailable, he/she should notify the rest of the committee beforehand.
  • If there is more than a week's delay on an issue from the maintainer's side, it is acceptable to ping him/her.
  • If there is more than a week's delay on an issue from the issue creator's side, the maintainer should feel free to close the issue if desired, with a comment explaining why it was closed.
  • Proposals that have widespread support, and are accompanied by patches (preferably with tests and documentation), should normally be accepted by the maintainer.
  • It is up to the maintainer to decide what "widespread" means; in particular, it does not always mean "a majority of those who responded". The majority-responder story is vulnerable to selection bias; e.g. 7 people (out of a client base of hundreds) say "add this function" but the maintainer thinks it will make the interface incrementally more complicated without sufficient benefit.
  • Where there is significant work involved in implementing a proposal, it is reasonable for a maintainer to ask for a patch. The principle is that maintainers are not obliged to do the work of implementing a proposal, even if it does enjoy wide support. For more substantial changes, it makes sense to develop the implementation in dialogue with the maintainer.

[edit] 5 Mistakes

People are fallible. The process above will allow some mistakes to be made. That's a conscious trade-off we're accepting now. If we had unlimited time and unlimited manpower, we may decide to discuss in detail each and every issue. However, that's not our reality: everyone involved has other responsibilities and does not have time or inclination to discuss in depth each issue.

Said another way: let's make progress with 95% accuracy rather than get bogged down in gridlock with 99% accuracy.

[edit] 6 Controversial decisions

It's impossible in this document to record all possible forms of a controversial decision. Here are some basic guidelines:

  • Adding a new, useful function under a clear name is probably not controversial
  • Breaking the API in any way is almost certainly controversial
  • Changing the semantics of an existing function is almost certainly controversial
  • Changes affecting Prelude and the Haskell Report are almost certainly controversial

It is important that, at the very least, the CLC receives an email on this topic. The individual maintainer is still in charge of the issue, but should give the CLC a chance to express an opinion. If after a reasonable amount of time (let's say one week) no objections are raised, the maintainer should feel free to move ahead with the change.

The CLC should repeat this decision making process again with more controversial issues. The prime example of this was the "burning bridges proposal": a change which drastically impacts Prelude should almost certainly be elevated to the libraries@ mailing list. Anything going to libraries@ should have at least a two week deadline on it.

At the end of the day, the CLC is still the body with decision making power. Explicitly: no single person should ever have veto power on a change. That includes the library maintainer; if the CLC votes against the library maintainer, that decision will stand. The CLC may itself decide to request support from others to make a decision, but is never required to do so.

[edit] 7 Guide to proposers

Previously (before February 2015), the initiative remained with the proposer for quite a while on the proposal process. The process described here is significantly different, so please note the change.

All library proposals should start on the relevant issue tracker. This may be a bug report, feature request, or even a complete patch/pull request. At this point, the library maintainer is responsible for taking next steps. Some example next steps would be to accept the patch, implement a bug fix, reject a feature request, or decide that this is a controversial decision that must be discussed with the CLC.

If the CLC decides that the discussion must be discussed with the libraries@ mailing list, the original proposer may be asked to moderate the libraries@ mailing list discussion. The general format for this is:

  • Send your proposal by email to the libraries@haskell.org mailing list (which you need to subscribe to before posting).
  • Set a deadline for discussion (no less than two weeks), and act as chair/moderator for the discussion.
  • Following discussion, it's the responsibility of the core libraries committee to determine if the proposal should be accepted. Send an email to the core libraries committee requesting a decision, optionally including your own summary of the mailing list discussion.
  • From that point forward, the CLC and maintainer will again be responsible for making a decision on how to proceed, and will inform the proposer and the mailing list. Possible decisions include acceptance, rejection, and requesting a patch be provided.

Here are desirable properties for a proposal and its implementation. The more of these properties your proposal or patch has, the more likely it is that the maintainer will adopt your idea. After all, to adopt it the maintainter will have to do whatever tasks you didn't do.

  • Description. A good proposal says clearly what you propose, why it is a good idea, and what its consequences would be.
  • Patch. Use darcs record or git commit (depending on what sort of repo the library lives in) to create it. Save the patch to a file, using darcs send --output or git format-patch. Make your changes against a copy of the master branch of the relevant library, and make sure it compiles.
  • Portability. Good code is portable. In particular, try to ensure the code runs in Hugs and GHC, and on Windows and Linux.
  • Style. Good code follows the conventions in the library you are modifying.
  • Documentation. Good code includes valid Haddock documentation.
  • Tests. Good patches have suitable tests for the library's testsuite.

[edit] 8 Guidance for maintainers

The principle is that we trust the maintainer to behave sensibly. The guidelines below are just that: guidelines, not rules. Still, the core libraries are used by many, many people, so maintainers should make every effort not to mess them up by accident.

  • API changes should be discussed on the libraries mailing list prior to making the change, even if the maintainer is the proposer. The maintainer still has ultimate say in what changes are made, but the community should have the opportunity to comment on changes. However, unanimity (or even a majority) is not required.
  • Every API change should be described precisely in the commit log. The commit logs should be sent to a public mailing list, or otherwise made easily available (e.g. via github), so that the community can keep an eye on changes and comment.
  • Backwards compatibility is important to many users. API changes are expected to retain backwards compatibility wherever possible. However, from time to time we may decide to have major revisions which are explicitly not backwards compatible; in these cases we may try to make the previous version of the package available concurrently, as in the base-3/base-4 switchover.
  • You don't need to consult the community for purely internal changes; i.e. changes that do not affect the library's clients.
  • Changes that simply widen the API by adding new functions are a bit of a grey area. It's better to consult the community, because there may be useful feedback about (say) the order of arguments, or the name of the function, or whatnot. On the other hand few clients will actually break if you add a new function to the API. Use your judgment.

Libraries maintained by the GHC team are subject to the GHC validation policy - patches will be tested for validation before committing (TestingPatches). Those packages not maintained by the GHC team will probably have a GHC lagging mirror repository that is subject to validation.

[edit] 9 See also