Difference between revisions of "Library submissions"
Jump to navigation
Jump to search
RossPaterson (talk | contribs) (tweaks, collect extra refs at end) |
(Replaced content with "== This page is outdated. Please refer to https://github.com/haskell/core-libraries-committee/blob/main/PROPOSALS.md instead ==") |
||
(81 intermediate revisions by 18 users not shown) | |||
Line 1: | Line 1: | ||
+ | == This page is outdated. Please refer to https://github.com/haskell/core-libraries-committee/blob/main/PROPOSALS.md instead == |
||
− | 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. |
||
− | |||
− | == 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 [http://darcs.net 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 [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. |
||
− | |||
− | 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]. |
||
− | |||
− | == 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]] |