|
|
| (63 intermediate revisions by 14 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) in packages that list ''libraries@haskell.org'' as maintainer.
| |
| We have been using it since October 2006.
| |
| | |
| In essence, we don't want proposals to go unnoticed, but changes to
| |
| basic interfaces also need thorough consideration.
| |
| | |
| == 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 [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. At the very least ensure the code runs in Hugs and GHC, and on Windows and Linux.
| |
| * ''Style''. Follow the conventions in the library you are modifying.
| |
| * ''Documentation''. It must include valid [http://haskell.org/haddock Haddock] documentation.
| |
| * ''Tests''. Code should ideally also come with suitable tests for the testsuite. There's currently some disagreement about what this means. Discussion of where we may want to head is in the [[library tests]] page.
| |
| | |
| == Submitting the proposal ==
| |
| | |
| * ''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>.
| |
| | |
| * ''Tracking''. [http://hackage.haskell.org/trac/ghc/newticket?type=proposal&component=libraries/base&milestone=Not+GHC 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 libraries@haskell.org, which you need to [http://www.haskell.org/mailman/listinfo/libraries subscribe] before posting. (In the future this should happen when you record the ticket, but we haven't set it up yet.) You may wish to include a pointer to updated Haddock documentation, if relevant.
| |
| | |
| If someone has done all this, they are entitled to expect feedback;
| |
| silence during the discussion period can be interpreted as consent.
| |
| | |
| 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 ==
| |
| | |
| * 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 (but please do include a link to the thread in the list archives too, so that people can review it if they wish)).
| |
| * 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 [http://hackage.haskell.org/trac/ghc/query?status=closed&group=component&type=proposal&order=priority archived past proposals].
| |
| | |
| Here is an example of how to [http://hackage.haskell.org/trac/ghc/ticket/966 summarise a successful submission].
| |
| | |
| == 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:Proposals| ]]
| |