Personal tools

Library submissions

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
(tweaks, collect extra refs at end)
Line 15: Line 15:
   
 
In order to ensure we have something concrete to discuss, please follow
 
In order to ensure we have something concrete to discuss, please follow
the following guidlines when creating a new proposal:
+
the following guidelines when creating a new proposal:
   
 
* ''Submission''. Proposed changes should be submitted to libraries@haskell.org, as a [http://darcs.net darcs] patch.
 
* ''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 branch of the relevant library.
 
* ''Patch''. The patch must compile against the head branch of the relevant library.
* ''Style'' The style of code should follow the conventions in the existing library. See also: [http://haskell.org/haskellwiki/Category:Style Style] and [http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions GHC Working Conventions].
+
* ''Style''. Follow the conventions in the library you are modifying.
* ''Documentation''. It must include valid [http://haskell.org/haddock Haddock documentation]
+
* ''Documentation''. It must include valid [http://haskell.org/haddock Haddock] documentation.
 
* ''Tests''. Code should also come with tests for the testsuite.
 
* ''Tests''. Code should also come with tests for the testsuite.
 
** Pure code should also come with [http://www.md.chalmers.se/~rjmh/QuickCheck/ QuickCheck] properties.
 
** Pure code should also come with [http://www.md.chalmers.se/~rjmh/QuickCheck/ QuickCheck] properties.
Line 26: Line 26:
 
* ''Portability''. Code should be portable. If it is not portable, reasons should be given. Ensure the code runs in at least Hugs and GHC, Windows and Linux.
 
* ''Portability''. Code should be portable. If it is not portable, reasons should be given. Ensure the code runs in at least Hugs and GHC, Windows and Linux.
   
To document the change, please [http://hackage.haskell.org/trac/ghc/newticket?type=proposal&component=libraries/base add a Trac ticket] of type ''proposal'' against the appropriate library component, and a timescale for consideration (to focus the community's attention):
+
To document the change, please [http://hackage.haskell.org/trac/ghc/newticket?type=proposal&component=libraries/base add a Trac ticket] of type ''proposal'' for the appropriate library component, and a timescale for consideration (to focus the community's attention):
   
 
* ''Tracking''. The submission's trac ticket should be included in the mail sent to the libraries list. Here are the [http://hackage.haskell.org/trac/ghc/query?status=new&status=assigned&status=reopened&group=component&type=proposal&order=priority proposals currently under consideration].
 
* ''Tracking''. The submission's trac ticket should be included in the mail sent to the libraries list. Here are the [http://hackage.haskell.org/trac/ghc/query?status=new&status=assigned&status=reopened&group=component&type=proposal&order=priority proposals currently under consideration].
 
== Submitting ==
 
 
* [http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions Guidelines for submitting via darcs]
 
   
 
== At the end of the discussion period ==
 
== At the end of the discussion period ==
   
 
* The proposer adds to the ticket a summary of the relevant parts of the discussion. (The summary is needed for anyone wondering about the change later: it's not reasonable to point people at a 50-message thread.)
 
* The proposer adds to the ticket a summary of the relevant parts of the discussion. (The summary is needed for anyone wondering about the change later: it's not reasonable to point people at a 50-message thread.)
* The ticket is closed (usually as ''fixed'' or ''wontfix'').
 
 
* If consensus was achieved, the change is made, with the commit message referring back to the ticket.
 
* If consensus was achieved, the change is made, with the commit message referring back to the ticket.
  +
* The ticket is closed (usually as ''fixed'' or ''wontfix'').
   
 
A deeply held disagreement at this point may require some form of government (voting, dictatorship, etc). This should be a rare event.
 
A deeply held disagreement at this point may require some form of government (voting, dictatorship, etc). This should be a rare event.
   
 
Here are the [http://hackage.haskell.org/trac/ghc/query?status=closed&group=component&type=proposal&order=priority archived past proposals].
 
Here are the [http://hackage.haskell.org/trac/ghc/query?status=closed&group=component&type=proposal&order=priority archived past proposals].
  +
  +
== 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]]

Revision as of 21:14, 25 October 2006

As the Haskell community has grown, and emphasis on development has moved from language to libraries, the need for a more formalised process for contributing to libraries has emerged. This page documents our 'best practices' for proposing changes to library interfaces (e.g. new modules or functions, removing functions), especially for modules in the base package.

In essence, we don't want proposals to go unnoticed, but changes to basic interfaces also need thorough consideration.

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.

1 Submitting a proposal

In order to ensure we have something concrete to discuss, please follow the following guidelines when creating a new proposal:

  • Submission. Proposed changes should be submitted to libraries@haskell.org, as a darcs patch.
  • Patch. The patch must compile against the head branch of the relevant library.
  • Style. Follow the conventions in the library you are modifying.
  • Documentation. It must include valid Haddock documentation.
  • 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, Windows and Linux.

To document the change, please add a Trac ticket of type proposal for the appropriate library component, and a timescale for consideration (to focus the community's attention):

2 At the end of the discussion period

  • The proposer adds to the ticket a summary of the relevant parts of the discussion. (The summary is needed for anyone wondering about the change later: it's not reasonable to point people at a 50-message thread.)
  • If consensus was achieved, the change is made, with the commit message referring back to the ticket.
  • The ticket is closed (usually as fixed or wontfix).

A deeply held disagreement at this point may require some form of government (voting, dictatorship, etc). This should be a rare event.

Here are the archived past proposals.

3 See also