Difference between revisions of "Library submissions"
Jump to navigation
Jump to search
(Replaced content with "== This page is outdated. Please refer to https://github.com/haskell/core-libraries-committee/blob/main/PROPOSALS.md instead ==") |
|||
(56 intermediate revisions by 11 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) 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>. |
||
− | |||
− | * ''Submission''. Start a new thread on the libraries@haskell.org mailing list (which you need to [http://www.haskell.org/mailman/listinfo/libraries subscribe] to before posting), with a subject beginning "Proposal:". Include a description of the change and the rationale, and attach the patch. You may wish to include a pointer to updated Haddock documentation, if relevant. You must also include a deadline for the discussion period; it must allow at least 2 weeks for discussion, but you may allow more - particularly if many people are likely to be away during the next 2 weeks. If discussion is still ongoing at the deadline, the discussion period can be extended. |
||
− | |||
− | If someone has done all this, they are entitled to expect feedback; |
||
− | silence during the discussion period can be interpreted as consent. |
||
− | |||
− | == At the end of the discussion period == |
||
− | |||
− | * Determine whether consensus for the change was reached. A deeply held disagreement at this point may require some form of governance (voting, dictatorship, etc). This should be a rare event. |
||
− | |||
− | * If consensus was achieved, file a [http://hackage.haskell.org/trac/ghc/newticket ticket] on the GHC trac, attaching the (revised if necessary) patch. As well as the description and rationale, include a link to the discussion in the mailing list archives, as well as a summary of the conversation (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)). |
||
− | |||
− | 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| ]] |