Difference between revisions of "Library submissions"

From HaskellWiki
Jump to: navigation, search
(say which packages this applies to)
(Replaced content with "== This page is outdated. Please refer to https://github.com/haskell/core-libraries-committee/blob/main/PROPOSALS.md instead ==")
(70 intermediate revisions by 15 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) for packages that list ''libraries@haskell.org'' as maintainer.
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:
* ''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 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.
** We're working on a framework for the [[Library_tests | library tests]].
== 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. (In the future this should happen when you record the ticket, but we haven't set it up yet.)
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.)
* 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]

Latest revision as of 00:30, 23 February 2022