Difference between revisions of "Library submissions"
Jump to navigation
Jump to search
RossPaterson (talk | contribs) (revert expansion of scope: this would need to be discussed on the libraries list, and doesn't reflect current practice) |
|||
| Line 24: | Line 24: | ||
* ''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>. |
* ''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. |
||
| − | * ''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''. |
||
If someone has done all this, they are entitled to expect feedback; |
If someone has done all this, they are entitled to expect feedback; |
||
silence during the discussion period can be interpreted as consent. |
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 == |
== At the end of the discussion period == |
||
| ⚫ | |||
| ⚫ | * |
||
| − | * If consensus was achieved, revise the patch as necessary, including the Trac ticket number, and commit it (or set the ticket state to "patch" so that someone will commit it for you). |
||
| − | * Close the ticket (usually as ''fixed'' or ''wontfix''). |
||
| − | |||
| ⚫ | |||
| ⚫ | * 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 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]. |
Here is an example of how to [http://hackage.haskell.org/trac/ghc/ticket/966 summarise a successful submission]. |
||
Revision as of 23:19, 2 February 2011
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 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 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 darcs patch of your change using darcs record, including a rationale for the change. Save the patch to a file, using darcs send --output.
- Submission. Start a new thread on the libraries@haskell.org mailing list (which you need to 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.
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 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 summarise a successful submission.
See also
- GHC Working Conventions, including guidelines for submitting patches via darcs.
- Notes on programming style