Difference between revisions of "Library submissions"

From HaskellWiki
Jump to: navigation, search
(A link to where the library repositories are is needed.)
(Replaced content with "== This page is outdated. Please refer to https://github.com/haskell/core-libraries-committee/blob/main/PROPOSALS.md instead ==")
(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]

Latest revision as of 00:30, 23 February 2022