Personal tools

Library submissions

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
(A link to where the library repositories are is needed.)
(revised submission process, plus silence=consent)
Line 17: Line 17:
 
the following guidelines:
 
the following guidelines:
   
* ''Patch''. The patch must compile against the head branch of the relevant library.
+
* ''Currency''. Make your changes against a copy of the HEAD branch of the [http://hackage.haskell.org/trac/ghc/wiki/DarcsRepositories relevant library], and make sure it compiles.
  +
* ''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.
 
* ''Style''. Follow the conventions in the library you are modifying.
 
* ''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.
Line 23: Line 23:
 
** 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.
 
** Impure code should have unit tests.
 
** 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.
 
   
 
== Submitting the proposal ==
 
== Submitting the proposal ==
   
* ''Tracking''. [http://hackage.haskell.org/trac/ghc/newticket?type=proposal&component=libraries/base Add a Trac ticket] of type ''proposal'' for the appropriate library component, with a timescale for consideration (to focus the community's attention).
+
* ''Patch''. Create a [http://darcs.net darcs] patch of your change using <tt>darcs record</tt>, including a rationale for the change. Save the patch to a file, using <tt>darcs send --output</tt>.
   
* ''Submission''. Create a [http://darcs.net darcs] patch of the [http://hackage.haskell.org/trac/ghc/wiki/DarcsRepositories library sources] using <tt>darcs record</tt>, including the Trac ticket number and a rationale, and submit the patch to [email protected] (You can do this with <tt>darcs send</tt>.)
+
* ''Tracking''. [http://hackage.haskell.org/trac/ghc/newticket?type=proposal&component=libraries/base Add a Trac ticket] of type ''proposal'' for the appropriate library component, with a timescale for consideration (to focus the community's attention for a limited period), adding the patch file as an attachment.
  +
  +
* ''Submission''. Send an email containing the Trac ticket number and description to [email protected] (In the future this should happen when you record the ticket, but we haven't set it up yet.)
   
 
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].
 
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].
  +
  +
If someone has done all this, they are entitled expect feedback;
  +
silence during the discussion period can be interpreted as consent.
   
 
== 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.)
+
* Add 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.
+
* If consensus was achieved, revise the patch as necessary, including the Trac ticket number, and commit it (or get someone to commit it for you).
* The ticket is closed (usually as ''fixed'' or ''wontfix'').
+
* Close the ticket (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.

Revision as of 09:38, 31 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.

Contents

1 Creating a proposal

In order to ensure we have something concrete to discuss, please follow the following guidelines:

  • Currency. Make your changes against a copy of the HEAD branch of the relevant library, and make sure it compiles.
  • 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.
  • 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.

2 Submitting the proposal

  • Patch. Create a darcs patch of your change using darcs record, including a rationale for the change. Save the patch to a file, using darcs send --output.
  • Tracking. Add a Trac ticket of type proposal for the appropriate library component, with a timescale for consideration (to focus the community's attention for a limited period), adding the patch file as an attachment.
  • Submission. Send an email containing the Trac ticket number and description to [email protected] (In the future this should happen when you record the ticket, but we haven't set it up yet.)

Here are the proposals currently under consideration.

If someone has done all this, they are entitled expect feedback; silence during the discussion period can be interpreted as consent.

3 At the end of the discussion period

  • Add 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, revise the patch as necessary, including the Trac ticket number, and commit it (or get someone to commit it for you).
  • Close the ticket (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.

4 See also