|
|
| (77 intermediate revisions by 16 users not shown) |
| Line 1: |
Line 1: |
| − | As the Haskell community has grown, and emphasis on development has
| + | == This page is outdated. Please refer to https://github.com/haskell/core-libraries-committee/blob/main/PROPOSALS.md instead == |
| − | 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.
| |
| − | | |
| − | == Creating a proposal ==
| |
| − | | |
| − | In order to ensure we have something concrete to discuss, please follow
| |
| − | the following guidelines:
| |
| − | | |
| − | * ''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 [http://haskell.org/haddock Haddock] documentation.
| |
| − | * ''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.
| |
| − | ** 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 ==
| |
| − | | |
| − | * ''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).
| |
| − | | |
| − | * ''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 libraries@haskell.org. (You can do this with <tt>darcs send</tt>.)
| |
| − | | |
| − | 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].
| |
| − | | |
| − | == 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 [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]]
| |