Difference between revisions of "Library submissions"

From HaskellWiki
Jump to navigation Jump to search
(notes)
m (minor: add a helpful link to the validation process)
(45 intermediate revisions by 14 users not shown)
Line 1: Line 1:
  +
This page describes the process for maintaining the
−
As the Haskell community has grown, and emphasis on development has
  
−
moved from language to libraries, the need for a more formalised process
 +
'''Core libraries'''. The core libraries are a subset of the packages in the
  +
Haskell Platform, and define basic APIs that are expected to be
−
for contributing to libraries has emerged. This page documents our
  
  +
available in any Haskell implementation. They are listed under "The Core Libraries" below.
−
'best practices' for proposing new library functions.
 
   
  +
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.]
−
In essence, we don't want proposals to go unnoticed, but changes to
  
−
basic interfaces also need thorough consideration.
 
   
  +
= General principles =
−
Under the old ad hoc system, unless a proposal meets with a chorus of
  
−
approval, the only way to get a decision is from SimonM or unilateral
  
−
action by some committer. This slowed development.
  
   
  +
* Each core package has a named maintainer, or small group of maintainers, who have commit access to the package.
−
== Submitting a proposal ==
  
   
  +
* 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).
−
In order to ensure we have something concrete to discuss, please follow
  
−
the following guidlines when creating a new proposal:
  
   
  +
* 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.
−
* ''Submission''. Proposed changes should be submitted to libraries@haskell.org, as a [http://darcs.net darcs] patch
 
−
* ''Patch''. The patch must compile against the head
  
−
* ''Documentation''. It must include valid Haddock documentation (you need [http://haskell.org/haddock Haddock] 0.8)
  
−
* ''Tests''. Code should also come with tests for the testsuite.
  
−
** Pure code should also come with QuickCheck properties
  
−
** Impure code should have unit tests.
 
−
* ''Portability''. Code should be portable. If it is not portable, reasons should be given. Ensure the code runs in at least Hugs and GHC.
  
   
−
To document the change, please [http://hackage.haskell.org/trac/ghc add a Trac ticket], and a timescale for consideration (to focus the community's attention):
  
   
  +
= Responsiveness =
−
* ''Tracking''. The submission's trac ticket should be included in the mail sent to the libraries list.
  
   
  +
* Third parties submitting proposals to the maintainer of a library can expect a timely and thoughtful response.
−
== Reaching consensus ==
  
  +
* 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.
  +
* 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 =
−
* At the end of the discussion period, the proposer adds to the ticket a summary of the relevant parts of the discussion, the ticket is archived and, if consensus was achieved, the change is made. (The summary is needed for anyone wondering about the change later: it's not reasonable to point people at a 50-message thread.)
  
   
  +
A "proposal" can be anything from a one-sentence suggestion to a fully-implemented, tested, and documented patch.
−
* A deeply held disagreement at the end of the discussion period may require some form of government (voting, dictatorship, etc). This should be a rare event.
  
  +
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).
  +
  +
* Set a deadline for discussion (no less than two weeks), and act as chair/moderator for the discussion.
  +
  +
* 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.
  +
  +
* 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.)
  +
  +
* 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.
  +
  +
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"
  +
! Package !! Maintainer
  +
|-
  +
| [http://hackage.haskell.org/package/array array] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/base base] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/containers containers] || Johan Tibell and Milan Straka
  +
|-
  +
| [http://hackage.haskell.org/package/deepseq deepseq] || Simon Marlow
  +
|-
  +
| [http://hackage.haskell.org/package/directory directory] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/extensible-exceptions extensible-exceptions] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/ghc-prim ghc-prim] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/hpc hpc] || Andy Gill
  +
|-
  +
| [http://hackage.haskell.org/package/mtl mtl] || Edward Kmett
  +
|-
  +
| [http://hackage.haskell.org/package/parallel parallel] || Simon Marlow
  +
|-
  +
| [http://hackage.haskell.org/package/pretty pretty] || David Terei
  +
|-
  +
| [http://hackage.haskell.org/package/process process] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/random random] || Ryan Newton
  +
|-
  +
| [http://hackage.haskell.org/package/template-haskell template-haskell] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/unix unix] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/Win32 Win32] || Bryan O'Sullivan
  +
|-
  +
| [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 following packages match the appropriate language standard, and as such cannot change independently. The code is maintained by the GHC team.
  +
  +
{| border="1"
  +
|-
  +
| [http://hackage.haskell.org/package/haskell2010 haskell2010] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/haskell98 haskell98] || GHC HQ
  +
|}
  +
  +
These packages are maintained only for backward compatibility, and are not expected to undergo API changes in the future.
  +
  +
{| border="1"
  +
|-
  +
| [http://hackage.haskell.org/package/old-locale old-locale] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/old-time old-time] || GHC HQ
  +
|}
  +
  +
= See also =
  +
  +
* [http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions GHC Working Conventions], including guidelines for submitting patches via darcs.
  +
* [http://haskell.org/haskellwiki/Category:Style Notes on programming style]
   
 
[[Category:Community]]
  
[[Category:Community]]
  +
[[Category:Proposals| ]]

Revision as of 15:27, 25 August 2011

This page describes the process for maintaining the 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.]

General principles

  • Each core package has a named maintainer, or small group of maintainers, who have commit access to the package.
  • 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).
  • 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.


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.
  • 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

A "proposal" can be anything from a one-sentence suggestion to a fully-implemented, tested, and documented patch. 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 subscribe to before posting).
  • Set a deadline for discussion (no less than two weeks), and act as chair/moderator for the discussion.
  • 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.
  • If the decision is positive, 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.)
  • 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.

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.

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.

The Core Libraries

The following packages constitute the core libraries:

Package Maintainer
array GHC HQ
base GHC HQ
containers Johan Tibell and Milan Straka
deepseq Simon Marlow
directory GHC HQ
extensible-exceptions GHC HQ
ghc-prim GHC HQ
hpc Andy Gill
mtl Edward Kmett
parallel Simon Marlow
pretty David Terei
process GHC HQ
random Ryan Newton
template-haskell GHC HQ
unix GHC HQ
Win32 Bryan O'Sullivan
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 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

These packages are maintained only for backward compatibility, and are not expected to undergo API changes in the future.

old-locale GHC HQ
old-time GHC HQ

See also

Retrieved from "https://wiki.haskell.org/index.php?title=Library_submissions&oldid=41763"