Difference between revisions of "Library submissions/NewDraft"

From HaskellWiki
Jump to: navigation, search
Line 1: Line 1:
= Core Library policies =
 
 
 
This page describes a proposed process for maintaining the
 
This page describes a proposed process for maintaining the
'''Core libraries'''.
+
'''Core libraries'''. The core libraries are a subset of the packages in the
  +
Haskell Platform, and define basic APIs that are expected to be
  +
available in any Haskell implementation. They are listed under "The Core Libraries" below.
   
Core libraries are particularly important, and as such we apply some (lightweight) policies to their development. In the past we used the [[Library_submissions]] process, but that was deemed to hamper productivity too much. The new policy puts more emphasis on leadership and empowers individual maintainers to make changes, while still allowing the community to make feedback, contributions, and proposals.
+
In the past we used the [[Library_submissions]] process for the core libraries, but that was deemed to hamper productivity too much. The new policy puts more emphasis on leadership and empowers individual maintainers to make changes, while still allowing the community to make feedback, contributions, and proposals.
   
 
Non-core libraries are, of course, managed by their own authors/maintainers (named in their .cabal file), using whatever policies those maintainers see fit. [Note: arguably the policies below might usefully be applied to all libraries embodied in the Haskell Platform, but that is a question for the HP team.]
 
Non-core libraries are, of course, managed by their own authors/maintainers (named in their .cabal file), using whatever policies those maintainers see fit. [Note: arguably the policies below might usefully be applied to all libraries embodied in the Haskell Platform, but that is a question for the HP team.]
   
== What are the Core Libraries? ==
 
  +
= General principles =
   
The following packages form the core libraries. They are a subset of the packages in the Haskell Platform, and define basic APIs that are expected to be available in any Haskell implementation:
 
  +
* Each core package has a named maintainer, or small group of maintainers, who have commit access to the package.
   
* [http://hackage.haskell.org/package/array array]
 
  +
* Third parties are encouraged to make proposals for changes, both to the library API and its implementation, by sending the proposal to the maintainer (CC'ing the libraries mailing list).
* [http://hackage.haskell.org/package/base base]
 
* [http://hackage.haskell.org/package/containers containers]
 
* [http://hackage.haskell.org/package/directory directory]
 
* [http://hackage.haskell.org/package/mtl mtl]
 
* [http://hackage.haskell.org/package/pretty pretty]
 
* [http://hackage.haskell.org/package/process process]
 
* [http://hackage.haskell.org/package/random random]
 
* [http://hackage.haskell.org/package/unix unix]
 
   
== Policies for development, and community involvement ==
 
  +
* The maintainer is trusted to decide what changes to make to the package, and when. They are strongly encouraged to follow the guidance below, but the general principle is: the community offers opinions, but the maintainers decide.
   
* '''Each core package has a named maintainer''', or small group of maintainers, who have commit access to the package.
 
   
* '''The maintainers are trusted''' to decide what changes to make to the package, and when. They are strongly encouraged to follow the guidance below, but the general principle is: the community offers opinions, but the maintainers decide.
 
  +
= Responsiveness =
   
* '''Third parties are encouraged to make proposals for API changes''' by sending them to the maintainers (CC'ing the libraries mailing list). Proposals that are accompanied by patches (preferably with tests and documentation), and have widespread support, should normally be accepted by the maintainer.
 
  +
* Third parties submitting proposals to the maintainer of a library can expect a timely and thoughtful response.
  +
* The more effort the proposer invests (for example, by constructing a patch rather than making an off-the-cuff suggestion) the more consideration s/he can reasonably expect.
  +
* Proposals that have widespread support, and are accompanied by patches (preferably with tests and documentation), should normally be accepted by the maintainer.
  +
* Where there is significant work involved in implementing a proposal, it is reasonable for a maintainer to ask for a patch. The principle is that maintainers are not obliged to do the work of implementing a proposal, even if it does enjoy wide support. For more substantial changes, it makes sense to develop the implementation in dialogue with the maintainer.
   
* '''Third parties can submit non-API changes''' as patches directly to the maintainer (CC'ing the libraries mailing list).
 
  +
= Guidance for proposers =
   
* '''Commit logs will be sent to a public mailing list''', or otherwise made easily available (e.g. via github), so that the community can keep an eye on changes and comment.
 
  +
A "proposal" can be anything from a one-sentence suggestion to a fully-implemented, tested, and documented patch.
  +
However, the more substantial the proposal the more attention you can expect. The process is this:
   
'''Guidance for maintainers''':
 
  +
* Send your proposal by email to the maintainer, with a copy to the libraries@haskell.org mailing list (which you need to [http://www.haskell.org/mailman/listinfo/libraries subscribe] to before posting).
* '''Every API change should be described precisely in the commit log.'''
 
   
* '''API changes should be discussed''' on the libraries mailing list prior to making the change. The maintainer still has ultimate say in what changes are made, but the community should have the opportunity to comment on changes. <br/>
 
  +
* Set a deadline for discussion (no less than two weeks), and act as chair/moderator for the discussion.
: Typically, the maintainer would specify the change, explain why they advocate it, and give a deadline for comments. The maintainer is trusted to use his or her judgement in responding to comments and adapting the proposal where appropriate. However, unaminity (or even a majority) is not required.
 
   
* '''Backwards compatibility''' is important to many users. API changes are expected to retain backwards compatibility wherever possible. However, from time to time we may decide to have major revisions which are explicitly not backwards compatible; in these cases we may try to make the previous version of the package available concurrently, as in the base-3/base-4 switchover.
 
  +
* At the end of the discussion period, summarise your understanding of the consensus (or lack thereof), including a link to the thread in the mailing list archives, and send the summary to the moderator for decision.
   
* '''Responsiveness.''' Third parties submitting proposals to the maintainer of a library can expect a timely and thoughtful response. The more effort the proposer invests (eg by constructing a patch rather than making an off-the-cuff suggestion) the more consideration s/he can reasonably expect.
 
  +
* For non-trivial changes the maintainer may ask for a patch. You may create the patch up front, and make it part of oyur proposal; or you may want to have some discussion about the design first, and only then roll up your sleeves to do the implementation; and for bigger jobs you may want to wait until the maintainer agrees in principle with the change.
   
Libraries maintained by the GHC team are subject to the GHC validation policy - patches will be tested for validation before committing. Those packages not maintained by the GHC team will probably have a GHC lagging mirror repository that is subject to validation.
 
  +
'''SLPJ: what about creating a ticket?'''
   
== Creating a proposal ==
 
  +
Here are desirable properties for a proposal and its implementation.
   
In order to ensure we have something concrete to discuss, please follow
 
  +
* '''Description'''. A good proposal says clearly ''what'' you propose, ''why'' it is a good idea, and what its consequences would be.
the following guidelines:
 
  +
* '''Patch'''. Use <tt>darcs record</tt> or <tt>git commit</tt> (depending on what sort of repo the library lives in) to create it. Save the patch to a file, using <tt>darcs send --output</tt> or <tt>git format-patch</tt>.
  +
* '''Currency'''. Make your changes against a copy of the master 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'''. Include valid [http://haskell.org/haddock Haddock] documentation.
  +
* '''Tests'''. Provide suitable tests for the library's testsuite.
   
* ''Currency''. Make your changes against a copy of the master branch of the [http://hackage.haskell.org/trac/ghc/wiki/DarcsRepositories relevant library], and make sure it compiles.
 
  +
= Guidance for maintainers =
* ''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 ===
 
  +
* '''API changes should be discussed''' on the libraries mailing list prior to making the change, even if the maintainer is the proposer. The maintainer still has ultimate say in what changes are made, but the community should have the opportunity to comment on changes. However, unaminity (or even a majority) is not required.
   
* ''Patch''. Create a [http://darcs.net darcs] or git patch (depending on what sort of repo the library lives in) of your change using <tt>darcs record</tt> or <tt>git commit -a</tt>, including a rationale for the change. Save the patch to a file, using <tt>darcs send --output</tt> or <tt>git format-patch</tt>.
 
  +
* '''Every API change should be described precisely in the commit log.''' The commit logs should be sent to a public mailing list, or otherwise made easily available (e.g. via github), so that the community can keep an eye on changes and comment.
   
* ''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.
 
  +
* '''Backwards compatibility''' is important to many users. API changes are expected to retain backwards compatibility wherever possible. However, from time to time we may decide to have major revisions which are explicitly not backwards compatible; in these cases we may try to make the previous version of the package available concurrently, as in the base-3/base-4 switchover.
   
If someone has done all this, they are entitled to expect feedback;
 
  +
Libraries maintained by the GHC team are subject to the GHC validation policy - patches will be tested for validation before committing. Those packages not maintained by the GHC team will probably have a GHC lagging mirror repository that is subject to validation.
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].
 
 
 
== Ex-core libraries ==
 
 
The following packages are also listed as maintained by <code>libraries@haskell.org</code>, but are not in fact maintained by the community as a whole. We plan to clarify the maintainership of these packages shortly.
 
 
These packages are not expected to undergo API changes in the future. The code will be maintained by the GHC team.
 
   
* [http://hackage.haskell.org/package/old-locale old-locale]
 
  +
= The Core Libraries =
* [http://hackage.haskell.org/package/old-time old-time]
 
   
These packages match the appropriate language standard, and as such cannot change independently. The code is maintained by the GHC team.
 
  +
The following packages constitute the core libraries:
   
* [http://hackage.haskell.org/package/haskell2010 haskell2010]
 
  +
{| border="1"
* [http://hackage.haskell.org/package/haskell98 haskell98]
 
  +
! Package !! Maintainer
  +
|-
  +
| [http://hackage.haskell.org/package/array array] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/base base] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/containers containers] || ???
  +
|-
  +
| [http://hackage.haskell.org/package/directory directory] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/mtl mtl] || ???
  +
|-
  +
| [http://hackage.haskell.org/package/pretty pretty] || ???
  +
|-
  +
| [http://hackage.haskell.org/package/process process] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/random random] || ???
  +
|-
  +
| [http://hackage.haskell.org/package/unix unix] || GHC HQ
  +
|-
  +
|-
  +
| [http://hackage.haskell.org/package/template-haskell template-haskell] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/parallel parallel] || Simon Marlow
  +
|-
  +
| [http://hackage.haskell.org/package/hpc hpc] || Andy Gill
  +
|-
  +
| [http://hackage.haskell.org/package/ghc-prim ghc-prim] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/extensible-exceptions extensible-exceptions] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/deepseq deepseq] || Simon Marlow
  +
|-
  +
| [http://hackage.haskell.org/package/Win32 Win32] || ???
  +
|}
   
These packages in fact have maintainers, in most cases the GHC team:
 
  +
The maintainer "GHC HQ" means Simon Marlow, Simon Peyton Jones, and Ian Lynagh. A "???" means that we need a maintainer.
   
* [http://hackage.haskell.org/package/template-haskell template-haskell]
 
  +
The following packages match the appropriate language standard, and as such cannot change independently. The code is maintained by the GHC team.
* [http://hackage.haskell.org/package/parallel parallel]
 
* [http://hackage.haskell.org/package/hpc hpc]
 
* [http://hackage.haskell.org/package/ghc-prim ghc-prim]
 
* [http://hackage.haskell.org/package/extensible-exceptions extensible-exceptions]
 
* [http://hackage.haskell.org/package/deepseq deepseq]
 
   
These packages are orphaned, and are looking for a maintainer:
 
  +
{| border="1"
  +
|-
  +
| [http://hackage.haskell.org/package/haskell2010 haskell2010] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/haskell98 haskell98] || GHC HQ
  +
|}
   
* [http://hackage.haskell.org/package/Win32 Win32]
 
  +
These packages are maintained only for backward compatibility, and are not expected to undergo API changes in the future.
   
  +
{| border="1"
  +
|-
  +
| [http://hackage.haskell.org/package/old-locale old-locale] || GHC HQ
  +
|-
  +
| [http://hackage.haskell.org/package/old-time old-time] || GHC HQ
  +
|}
   
== See also ==
+
= See also =
   
 
* [http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions GHC Working Conventions], including guidelines for submitting patches via darcs.
 
* [http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions GHC Working Conventions], including guidelines for submitting patches via darcs.

Revision as of 23:01, 18 May 2011

This page describes a proposed process for maintaining the Core libraries. The core libraries are a subset of the packages in the Haskell Platform, and define basic APIs that are expected to be available in any Haskell implementation. They are listed under "The Core Libraries" below.

In the past we used the Library_submissions process for the core libraries, but that was deemed to hamper productivity too much. The new policy puts more emphasis on leadership and empowers individual maintainers to make changes, while still allowing the community to make feedback, contributions, and proposals.

Non-core libraries are, of course, managed by their own authors/maintainers (named in their .cabal file), using whatever policies those maintainers see fit. [Note: arguably the policies below might usefully be applied to all libraries embodied in the Haskell Platform, but that is a question for the HP team.]

General principles

  • Each core package has a named maintainer, or small group of maintainers, who have commit access to the package.
  • Third parties are encouraged to make proposals for changes, both to the library API and its implementation, by sending the proposal to the maintainer (CC'ing the libraries mailing list).
  • The maintainer is trusted to decide what changes to make to the package, and when. They are strongly encouraged to follow the guidance below, but the general principle is: the community offers opinions, but the maintainers decide.


Responsiveness

  • Third parties submitting proposals to the maintainer of a library can expect a timely and thoughtful response.
  • The more effort the proposer invests (for example, by constructing a patch rather than making an off-the-cuff suggestion) the more consideration s/he can reasonably expect.
  • Proposals that have widespread support, and are accompanied by patches (preferably with tests and documentation), should normally be accepted by the maintainer.
  • Where there is significant work involved in implementing a proposal, it is reasonable for a maintainer to ask for a patch. The principle is that maintainers are not obliged to do the work of implementing a proposal, even if it does enjoy wide support. For more substantial changes, it makes sense to develop the implementation in dialogue with the maintainer.

Guidance for proposers

A "proposal" can be anything from a one-sentence suggestion to a fully-implemented, tested, and documented patch. However, the more substantial the proposal the more attention you can expect. The process is this:

  • Send your proposal by email to the maintainer, with a copy to the libraries@haskell.org mailing list (which you need to subscribe to before posting).
  • Set a deadline for discussion (no less than two weeks), and act as chair/moderator for the discussion.
  • At the end of the discussion period, summarise your understanding of the consensus (or lack thereof), including a link to the thread in the mailing list archives, and send the summary to the moderator for decision.
  • For non-trivial changes the maintainer may ask for a patch. You may create the patch up front, and make it part of oyur proposal; or you may want to have some discussion about the design first, and only then roll up your sleeves to do the implementation; and for bigger jobs you may want to wait until the maintainer agrees in principle with the change.

SLPJ: what about creating a ticket?

Here are desirable properties for a proposal and its implementation.

  • Description. A good proposal says clearly what you propose, why it is a good idea, and what its consequences would be.
  • Patch. Use darcs record or git commit (depending on what sort of repo the library lives in) to create it. Save the patch to a file, using darcs send --output or git format-patch.
  • Currency. Make your changes against a copy of the master 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. Include valid Haddock documentation.
  • Tests. Provide suitable tests for the library's testsuite.

Guidance for maintainers

  • API changes should be discussed on the libraries mailing list prior to making the change, even if the maintainer is the proposer. The maintainer still has ultimate say in what changes are made, but the community should have the opportunity to comment on changes. However, unaminity (or even a majority) is not required.
  • Every API change should be described precisely in the commit log. The commit logs should be sent to a public mailing list, or otherwise made easily available (e.g. via github), so that the community can keep an eye on changes and comment.
  • Backwards compatibility is important to many users. API changes are expected to retain backwards compatibility wherever possible. However, from time to time we may decide to have major revisions which are explicitly not backwards compatible; in these cases we may try to make the previous version of the package available concurrently, as in the base-3/base-4 switchover.

Libraries maintained by the GHC team are subject to the GHC validation policy - patches will be tested for validation before committing. Those packages not maintained by the GHC team will probably have a GHC lagging mirror repository that is subject to validation.

The Core Libraries

The following packages constitute the core libraries:

Package Maintainer
array GHC HQ
base GHC HQ
containers  ???
directory GHC HQ
mtl  ???
pretty  ???
process GHC HQ
random  ???
unix GHC HQ
template-haskell GHC HQ
parallel Simon Marlow
hpc Andy Gill
ghc-prim GHC HQ
extensible-exceptions GHC HQ
deepseq Simon Marlow
Win32  ???

The maintainer "GHC HQ" means Simon Marlow, Simon Peyton Jones, and Ian Lynagh. A "???" means that we need a maintainer.

The following packages match the appropriate language standard, and as such cannot change independently. The code is maintained by the GHC team.

haskell2010 GHC HQ
haskell98 GHC HQ

These packages are maintained only for backward compatibility, and are not expected to undergo API changes in the future.

old-locale GHC HQ
old-time GHC HQ

See also