Difference between revisions of "Core Libraries Committee"

From HaskellWiki
Jump to navigation Jump to search
(much more complete/clear, update many things)
(8 intermediate revisions by 5 users not shown)
Line 1: Line 1:
  +
This page describes the entity known as the '''Core Libraries Committee''' (CLC), the libraries it concerns itself with, known as '''core libraries''' (LIBRARIES), and the relationship
−
To contact the Haskell Core Libraries Committee, send email to '''core-libraries-committee [AT] haskell.org'''. CC [http://www.haskell.org/haskellwiki/Library_submissions#Guidance_for_proposers libraries@haskell.org] if you want to reach a wider audience.
  
  +
between the two. The relationship consists of responsibilities
  +
and powers of CLC.
   
  +
= CLC Personnel =
−
== Responsibilities ==
  
−  
−
The [[Core Libraries Committee]] acts as the ''Maintainer'' per the [[Library submissions]] guidelines for many of the [http://www.haskell.org/haskellwiki/Library_submissions#The_Core_Libraries core libraries] that make up the Haskell Platform.
  
   
 
== Current members ==
  
== Current members ==
  +
* Daniel Cartwright (referred to in this document as "chessai") (chair, term ending 2021)
  +
* Cale Gibbard (term ending 2023)
  +
* Edward Kmett (advisory role, term ending 2020)
  +
* Andrew Thaddeus Martin (term ending 2021)
  +
* Eric Mertens (term ending June 2022)
  +
* Neil Mitchell (term ending 2020)
  +
* Emily Pillmore (term ending 2023)
  +
* Herbert Valerio Riedel (term ending 2022)
  +
* George Wilson (term ending 2022)
   
  +
== Contact ==
−
* Edward Kmett (chair)
  
  +
e-mail: '''core-libraries-committee [AT] haskell.org'''.
−
* Eric Mertens (Term ending June 2017)
  
  +
CC '''libraries [AT] haskell.org''' if you want to reach a wider
−
* Dan Doel
  
  +
audience.
−
* Michael Snoyman
  
−
* Luite Stegeman (Term ending June 2017)
  
−
* Joachim Breitner
  
−  
−
e-mail: core-libraries-committee [AT] haskell.org
  
−  
−
GitHub: The [https://github.com/orgs/haskell/teams/core-libraries-committee Core Libraries Committee Team] (link only resolves if you are a member of [https://github.com/haskell github.com/haskell]) can be mentioned/notified in GitHub conversations by using the syntax <code>@haskell/core-libraries-committee</code>.
  
   
 
== Operation ==
  
== Operation ==
  +
The committee consists of 9 members. Members are expected to serve a 3 year term, and terms are staggered so that roughly 3 members have their terms end each year, at the end of December.
−  
−
The committee consists of 9 members. Members are expected to serve a 3 year term, and terms are staggered so that roughly 3 members have their terms end each year, at the end of June. We currently have 3 vacancies as a result of [https://groups.google.com/forum/#!topic/haskell-core-libraries/VHQ4cIClI6A expanding the committee].
  
   
 
The members will elect one of their number to be chair each year. The chair is responsible for making sure that things keep moving, and to ensure that a conclusion is reached on any issues raised.
  
The members will elect one of their number to be chair each year. The chair is responsible for making sure that things keep moving, and to ensure that a conclusion is reached on any issues raised.
Line 26: Line 28:
 
When a member steps down, either because they have reached the end of their term or because other circumstances require them to step down early, open self-nominations will be sought from the community via the libraries@ mailing list. Previous committee members, including those who have just stepped down, will also be eligible for nomination.
  
When a member steps down, either because they have reached the end of their term or because other circumstances require them to step down early, open self-nominations will be sought from the community via the libraries@ mailing list. Previous committee members, including those who have just stepped down, will also be eligible for nomination.
   
−
The committee will then select a replacement from amongst those nominated. For the purposes of considering nominations, the committee will include any outgoing members who are seeking re-appointment.
 +
The committee will then select a replacement from amongst those nominated. For the purposes of considering nominations, the committee will include any outgoing members who are not seeking re-appointment.
   
 
The committee replacement process is intentionally currently very light. As we get more experience, we may wish to change it, e.g. by having a larger subset of "the community" vote on nominations.
  
The committee replacement process is intentionally currently very light. As we get more experience, we may wish to change it, e.g. by having a larger subset of "the community" vote on nominations.
Line 32: Line 34:
 
It is expected the committee will discuss any matters brought to it amongst themselves, and if they think appropriate, with the wider community via [http://www.haskell.org/pipermail/libraries/ libraries@haskell.org], to try to reach consensus. Ultimately, the committee will make decisions by more than half of the membership voting for a particular outcome. These rules of operation may also be changed in the same way.
  
It is expected the committee will discuss any matters brought to it amongst themselves, and if they think appropriate, with the wider community via [http://www.haskell.org/pipermail/libraries/ libraries@haskell.org], to try to reach consensus. Ultimately, the committee will make decisions by more than half of the membership voting for a particular outcome. These rules of operation may also be changed in the same way.
   
  +
= Core Libraries =
−
== Resources ==
  
  +
  +
== Definition ==
  +
A '''core''' library is one which is maintained by CLC.
  +
This section aims to provide guidelines for why a library might
  +
come to be considered '''core'''.
  +
  +
A library is very likely to be considered '''core''' if it ships with GHC. This can happen for one of three reasons:
  +
  +
* It is part of the Haskell Language Standard
  +
* It is tightly coupled to GHC’s implementation of some feature. These libraries cannot be changed independently of GHC. You could think of them as part of GHC, part that happens to be implemented in library code.
  +
* It is used to build GHC itself. We have to ship these libraries with GHC because ghc itself is a package, and so we must have installed packages for anything the ghc package depends on.
  +
  +
There are libraries that are considered '''core''' which do not ship with GHC. There should be a clear and enumerable set of
  +
criteria for why these are considered '''core''', though as of right now there is no such set. Currently, the rough criteria
  +
is that these packages have reached a critical mass of reverse dependencies and adoption in the community, such that they
  +
have become "important". TODO: make this paragraph less hand-wavy.
  +
  +
There are libraries that ship with GHC, but are not considered '''core'''. Those packages are the following:
  +
{| border="1"
  +
! Package !! Maintainer !! Issue Tracker
  +
|-
  +
| [http://hackage.haskell.org/package/containers containers] || David Feuer || [https://github.com/haskell/containers/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/hoopl hoopl] || Ning Wang || [https://github.com/haskell/hoopl/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/parallel parallel] || Simon Marlow || [https://github.com/haskell/parallel/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/pretty pretty] || David Terei || [https://github.com/haskell/pretty/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/time time] || Ashley Yakeley || [https://github.com/haskell/time/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/xhtml xhtml] || Chris Dornan || [https://github.com/haskell/xhtml/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/ghc-prim ghc-prim] || GHC HQ || [http://ghc.haskell.org/trac/ghc/newticket?component=libraries%20%28other%29&keywords=ghc-prim GHC Trac]
  +
|-
  +
| [http://hackage.haskell.org/package/hpc hpc] || GHC HQ || [http://ghc.haskell.org/trac/ghc/newticket?component=Code%20Coverage GHC Trac]
  +
|-
  +
|}
  +
  +
== Current Core Libraries ==
  +
The following table lists the libraries maintained by the CLC, their primary maintainers, and the issue tracker for filing bugs and feature requests.
  +
  +
{| border="1"
  +
! Package !! Maintainer !! Issue Tracker
  +
|-
  +
| [http://hackage.haskell.org/package/array array] || Herbert Valerio Riedel || [https://ghc.haskell.org/trac/ghc/newticket?component=libraries%20%28other%29&keywords=array GHC Trac]
  +
|-
  +
| [http://hackage.haskell.org/package/base base] || chessai || [https://ghc.haskell.org/trac/ghc/newticket?component=libraries%20%28base GHC Trac]
  +
|-
  +
| [http://hackage.haskell.org/package/deepseq deepseq] || Herbert Valerio Riedel || [https://github.com/haskell/deepseq/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/directory directory] || Phil Ruffwind, Elliot Robinson || [https://github.com/haskell/directory/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/filepath filepath] || Neil Mitchell || [https://github.com/haskell/filepath/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/mtl mtl] || Edward Kmett, chessai || [https://github.com/ekmett/mtl/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/primitive primitive] || Andrew Martin || [https://github.com/haskell/primitive/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/process process] || Michael Snoyman || [https://github.com/haskell/process/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/random random] || Alexey Kuleshevich, Dominic Steinitz, Leonhard Markert, Alexey Khuedyakov, Andrew Lelechenko || [https://github.com/haskell/random/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/stm stm] || GHC HQ || [https://ghc.haskell.org/trac/ghc/newticket?component=libraries%20%28other%29&keywords=stm GHC Trac]
  +
|-
  +
| [http://hackage.haskell.org/package/template-haskell template-haskell] || Edward Kmett || [http://ghc.haskell.org/trac/ghc/newticket?component=Template%20Haskell GHC Trac]
  +
|-
  +
| [http://hackage.haskell.org/package/unix unix] || Herbert Valerio Riedel, Elliot Robinson || [https://github.com/haskell/unix/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/vector vector] || Alexey Kuleshevich, Alexey Khudyakov, Andrew Lelechenko || [https://github.com/haskell/vector/issues Github]
  +
|-
  +
| [http://hackage.haskell.org/package/Win32 Win32] || [https://ghc.haskell.org/trac/ghc/wiki/WindowsTaskForce Windows Task Force] || [https://github.com/haskell/win32/issues Github]
  +
|-
  +
|}
  +
  +
The maintainer "GHC HQ" means Simon Marlow, Simon Peyton Jones, Herbert Valerio Riedel, and Ben Gamari. The GHC HQ email is ghc-devs@haskell.org.
  +
  +
= CLC powers and responsibilities =
  +
  +
== Ownership of Core Libraries ==
  +
Ownership is not the same thing as maintainership. Roughly,
  +
ownership means that the health and maintenance of LIBRARIES
  +
are a responsibility/duty of the CLC, and collectively "owned"
  +
by the CLC, and no one individual or other entity. Maintainers
  +
appointed to maintain core libraries must acknowledge this
  +
ownership by the CLC.
  +
  +
== Maintainership of Core Libraries ==
  +
To ensure the health of LIBRARIES, we should strive to meet
  +
the following goals:
  +
* Bugs are resolved
  +
* Feature requests can be implemented
  +
* Patches can be merged
  +
* All of this can be done with minimal friction for users of these libraries
  +
  +
Maintainership of a library involves contributing to the library;
  +
by contributing actual code, reviewing PRs/MRs, and educating
  +
users of the library in understanding the library. A key part
  +
in maintainership is encouraging contributions by
  +
non-maintainers, i.e. outside Haskell users. Having users
  +
contribute to libraries reduces the burden on maintainers to do
  +
all of the work and boosts the morale of both maintainers and
  +
users. Additionally, because most changes introduced by users
  +
are need-driven, this ensures that users are having their needs
  +
met by core libraries.
  +
  +
CLC should support appointed maintainers via co-maintenance,
  +
reviews, guidance, and any other useful contributions.
  +
  +
== Appointing Maintainers of Core Libraries ==
  +
The CLC cannot possibly shoulder all of the maintenance
  +
burden of the core libraries. It is therefore in the best
  +
interest of the Haskell community to appoint outside maintainers
  +
to libraries, to ensure the development and health of those
  +
libraries.
  +
  +
=== Number of maintainers ===
  +
Each library needs at least two maintainers. Depending on
  +
the complexity of the library, more maintainers may be needed.
  +
For example, the `filepath` library is very stable and requires
  +
little work, so really only one maintainer is needed most of the
  +
time; but a second maintainer is useful, because humans have
  +
lives and may need to tend to things outside of Haskell.
  +
For libraries with such little maintenance burden as `filepath`,
  +
the second maintainer may as well be the CLC itself, and needn't
  +
be a dedicated person. For more complicated libraries like
  +
`vector` or `random`, three to five people is preferable.
  +
  +
Too many maintainers can make consensus hard to achieve, and
  +
features will grind to a halt.
  +
  +
=== Maintainer qualities ===
  +
CLC should ensure that maintainers:
  +
* are competent Haskellers, often experts
  +
* understand the scope and goals of the library they are appointed to maintain
  +
* are good communicators
  +
* are calm and collected
  +
* are generally considered reasonable
  +
* are trustworthy
  +
  +
=== Un-appointing maintainers ===
  +
Maintainers of core libraries (whether in the CLC or not) can be
  +
un-appointed by the CLC in extremis. This is not to be exercised
  +
lightly. There is not much precedent for this, so such situations
  +
should be handled on a case-by-case basis.
  +
  +
Sometimes maintainers realise that they are no longer equipped
  +
to maintain a library, because of loss of interest, life, too
  +
much on their plate, etc. (stuff happens). In this case, the
  +
maintainer should be thanked for their time, and the CLC should
  +
find a new maintainer to take their place. The CLC should
  +
collectively act in place of the maintainer while a new one is
  +
found, if their vacancy left a maintainership gap that needs
  +
filling.
  +
  +
== Deciding Core Library APIs ==
  +
The API of a library is both its "shape" (roughly, its functions and data types) and its semantics (roughly, correctness and performance). This does not include library implementation. As long as a library implementation satisfies the specified shape and semantics, maintainers should be trusted to do the right thing and not be micromanaged.
  +
  +
If a maintainer wants to introduce some "controversial" (discussed below) change to the API of a library, CLC should be consulted.
  +
  +
=== Guidance for maintainers regarding APIs ===
  +
The principle is that we trust the maintainer to behave sensibly. The guidelines below are just that: guidelines, not rules. Still, LIBRARIES are used by many, many people, so maintainers should make every effort not to mess them up by accident.
  +
  +
* 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, unanimity (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.
  +
* You don't need to consult the community for purely internal changes; i.e. changes that do not affect the library's clients.
  +
* Changes that simply widen the API by adding new functions are a bit of a grey area. It's better to consult the community, because there may be useful feedback about (say) the order of arguments, or the name of the function, or whatnot. On the other hand few clients will actually break if you add a new function to the API. Use your judgment.
  +
  +
Libraries maintained by the GHC team are subject to the GHC validation policy - patches will be tested for validation before committing (TestingPatches). Those packages not maintained by the GHC team will probably have a GHC lagging mirror repository that is subject to validation.
  +
  +
=== Controversial decisions ===
  +
It's impossible to record all possible forms of a controversial decision. Here are some basic guidelines:
  +
  +
* Adding a new, useful function under a clear name is probably not controversial
  +
* Breaking the API in any way is almost certainly controversial
  +
* Changing the semantics of an existing function is almost certainly controversial
  +
* Changes affecting Prelude and the Haskell Report are almost certainly controversial
  +
  +
It is important that, at the very least, the CLC receives an email on this topic. The individual maintainer is still in charge of the issue, but should give the CLC a chance to express an opinion. If after a reasonable amount of time (let's say one week) no objections are raised, the maintainer should feel free to move ahead with the change.
  +
  +
The CLC should repeat this decision making process again with more controversial issues. The prime example of this was the "burning bridges proposal": a change which drastically impacts Prelude should almost certainly be elevated to the libraries@ mailing list. Anything going to libraries@ should have at least a two week deadline on it.
  +
  +
At the end of the day, the CLC is still the body with decision making power. Explicitly: no single person should ever have veto power on a change. That includes the library maintainer; if the CLC votes against the library maintainer, that decision will stand. The CLC may itself decide to request support from others to make a decision, but is never required to do so.
  +
  +
== Library Adoption ==
  +
If a library reaches a critical mass (becomes so important to
  +
the community, it can be seen as core), the CLC should make
  +
efforts to adopt that library, coordinating with library
  +
maintainers.
  +
  +
The procedure for doing so is roughly:
  +
  +
* CLC recognises a library not in LIBRARIES as core
  +
* Reach out to the maintainer(s) of the recognised package about migrating its ownership to CLC, keeping the existing maintainer(s).
  +
* If they are cooperative, the library will become a part of LIBRARIES, and all things that apply to LIBRARIES and CLC as per this document will apply to that library.
  +
* If they are not cooperative, CLC will respect the rights of maintainers, and allow the package to remain separate. However, CLC should be encouraged to contribute to that package going forward, and co-maintain if possible.
  +
  +
There are some clear candidates for adoption:
  +
* text
  +
* bytestring
  +
* containers
  +
* unordered-containers
  +
* pretty
  +
* time
   
  +
These are all packages which are "core" in that they ship with
−
If any member of the community wishes to raise any issue with the committee, they may contact it by e-mailing core-libraries-committee [AT] haskell.org (fairly narrow distribution) ([https://groups.google.com/forum/#!forum/haskell-core-libraries archives]) or libraries@haskell.org ([http://www.haskell.org/pipermail/libraries/ much broader distribution]).
  
  +
GHC and/or have reached critical mass, but are not currently owned by the CLC).
   
  +
== Haskell Library Report ==
−
Material related to active proposals, resolutions, meeting minutes, etc. can be found at https://prime.haskell.org/wiki/Libraries
  
  +
CLC is tasked with updating and defining the part of the
  +
Haskell Language Report concerning the `base` library.
   
  +
There is a pretty clear breakdown of this issue and some
−
[[Category:Community]]
  
  +
discussion here: https://groups.google.com/g/haskell-core-libraries/c/2malEk5df6A/m/a3cpqQANCgAJ, which should eventually
  +
be folded into this page.

Revision as of 21:06, 2 August 2020

This page describes the entity known as the Core Libraries Committee (CLC), the libraries it concerns itself with, known as core libraries (LIBRARIES), and the relationship between the two. The relationship consists of responsibilities and powers of CLC.

CLC Personnel

Current members

  • Daniel Cartwright (referred to in this document as "chessai") (chair, term ending 2021)
  • Cale Gibbard (term ending 2023)
  • Edward Kmett (advisory role, term ending 2020)
  • Andrew Thaddeus Martin (term ending 2021)
  • Eric Mertens (term ending June 2022)
  • Neil Mitchell (term ending 2020)
  • Emily Pillmore (term ending 2023)
  • Herbert Valerio Riedel (term ending 2022)
  • George Wilson (term ending 2022)

Contact

e-mail: core-libraries-committee [AT] haskell.org. CC libraries [AT] haskell.org if you want to reach a wider audience.

Operation

The committee consists of 9 members. Members are expected to serve a 3 year term, and terms are staggered so that roughly 3 members have their terms end each year, at the end of December.

The members will elect one of their number to be chair each year. The chair is responsible for making sure that things keep moving, and to ensure that a conclusion is reached on any issues raised.

When a member steps down, either because they have reached the end of their term or because other circumstances require them to step down early, open self-nominations will be sought from the community via the libraries@ mailing list. Previous committee members, including those who have just stepped down, will also be eligible for nomination.

The committee will then select a replacement from amongst those nominated. For the purposes of considering nominations, the committee will include any outgoing members who are not seeking re-appointment.

The committee replacement process is intentionally currently very light. As we get more experience, we may wish to change it, e.g. by having a larger subset of "the community" vote on nominations.

It is expected the committee will discuss any matters brought to it amongst themselves, and if they think appropriate, with the wider community via libraries@haskell.org, to try to reach consensus. Ultimately, the committee will make decisions by more than half of the membership voting for a particular outcome. These rules of operation may also be changed in the same way.

Core Libraries

Definition

A core library is one which is maintained by CLC. This section aims to provide guidelines for why a library might come to be considered core.

A library is very likely to be considered core if it ships with GHC. This can happen for one of three reasons:

  • It is part of the Haskell Language Standard
  • It is tightly coupled to GHC’s implementation of some feature. These libraries cannot be changed independently of GHC. You could think of them as part of GHC, part that happens to be implemented in library code.
  • It is used to build GHC itself. We have to ship these libraries with GHC because ghc itself is a package, and so we must have installed packages for anything the ghc package depends on.

There are libraries that are considered core which do not ship with GHC. There should be a clear and enumerable set of criteria for why these are considered core, though as of right now there is no such set. Currently, the rough criteria is that these packages have reached a critical mass of reverse dependencies and adoption in the community, such that they have become "important". TODO: make this paragraph less hand-wavy.

There are libraries that ship with GHC, but are not considered core. Those packages are the following:

Package Maintainer Issue Tracker
containers David Feuer Github
hoopl Ning Wang Github
parallel Simon Marlow Github
pretty David Terei Github
time Ashley Yakeley Github
xhtml Chris Dornan Github
ghc-prim GHC HQ GHC Trac
hpc GHC HQ GHC Trac

Current Core Libraries

The following table lists the libraries maintained by the CLC, their primary maintainers, and the issue tracker for filing bugs and feature requests.

Package Maintainer Issue Tracker
array Herbert Valerio Riedel GHC Trac
base chessai GHC Trac
deepseq Herbert Valerio Riedel Github
directory Phil Ruffwind, Elliot Robinson Github
filepath Neil Mitchell Github
mtl Edward Kmett, chessai Github
primitive Andrew Martin Github
process Michael Snoyman Github
random Alexey Kuleshevich, Dominic Steinitz, Leonhard Markert, Alexey Khuedyakov, Andrew Lelechenko Github
stm GHC HQ GHC Trac
template-haskell Edward Kmett GHC Trac
unix Herbert Valerio Riedel, Elliot Robinson Github
vector Alexey Kuleshevich, Alexey Khudyakov, Andrew Lelechenko Github
Win32 Windows Task Force Github

The maintainer "GHC HQ" means Simon Marlow, Simon Peyton Jones, Herbert Valerio Riedel, and Ben Gamari. The GHC HQ email is ghc-devs@haskell.org.

CLC powers and responsibilities

Ownership of Core Libraries

Ownership is not the same thing as maintainership. Roughly, ownership means that the health and maintenance of LIBRARIES are a responsibility/duty of the CLC, and collectively "owned" by the CLC, and no one individual or other entity. Maintainers appointed to maintain core libraries must acknowledge this ownership by the CLC.

Maintainership of Core Libraries

To ensure the health of LIBRARIES, we should strive to meet the following goals:

  • Bugs are resolved
  • Feature requests can be implemented
  • Patches can be merged
  • All of this can be done with minimal friction for users of these libraries

Maintainership of a library involves contributing to the library; by contributing actual code, reviewing PRs/MRs, and educating users of the library in understanding the library. A key part in maintainership is encouraging contributions by non-maintainers, i.e. outside Haskell users. Having users contribute to libraries reduces the burden on maintainers to do all of the work and boosts the morale of both maintainers and users. Additionally, because most changes introduced by users are need-driven, this ensures that users are having their needs met by core libraries.

CLC should support appointed maintainers via co-maintenance, reviews, guidance, and any other useful contributions.

Appointing Maintainers of Core Libraries

The CLC cannot possibly shoulder all of the maintenance burden of the core libraries. It is therefore in the best interest of the Haskell community to appoint outside maintainers to libraries, to ensure the development and health of those libraries.

Number of maintainers

Each library needs at least two maintainers. Depending on the complexity of the library, more maintainers may be needed. For example, the `filepath` library is very stable and requires little work, so really only one maintainer is needed most of the time; but a second maintainer is useful, because humans have lives and may need to tend to things outside of Haskell. For libraries with such little maintenance burden as `filepath`, the second maintainer may as well be the CLC itself, and needn't be a dedicated person. For more complicated libraries like `vector` or `random`, three to five people is preferable.

Too many maintainers can make consensus hard to achieve, and features will grind to a halt.

Maintainer qualities

CLC should ensure that maintainers:

  • are competent Haskellers, often experts
  • understand the scope and goals of the library they are appointed to maintain
  • are good communicators
  • are calm and collected
  • are generally considered reasonable
  • are trustworthy

Un-appointing maintainers

Maintainers of core libraries (whether in the CLC or not) can be un-appointed by the CLC in extremis. This is not to be exercised lightly. There is not much precedent for this, so such situations should be handled on a case-by-case basis.

Sometimes maintainers realise that they are no longer equipped to maintain a library, because of loss of interest, life, too much on their plate, etc. (stuff happens). In this case, the maintainer should be thanked for their time, and the CLC should find a new maintainer to take their place. The CLC should collectively act in place of the maintainer while a new one is found, if their vacancy left a maintainership gap that needs filling.

Deciding Core Library APIs

The API of a library is both its "shape" (roughly, its functions and data types) and its semantics (roughly, correctness and performance). This does not include library implementation. As long as a library implementation satisfies the specified shape and semantics, maintainers should be trusted to do the right thing and not be micromanaged.

If a maintainer wants to introduce some "controversial" (discussed below) change to the API of a library, CLC should be consulted.

Guidance for maintainers regarding APIs

The principle is that we trust the maintainer to behave sensibly. The guidelines below are just that: guidelines, not rules. Still, LIBRARIES are used by many, many people, so maintainers should make every effort not to mess them up by accident.

  • 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, unanimity (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.
  • You don't need to consult the community for purely internal changes; i.e. changes that do not affect the library's clients.
  • Changes that simply widen the API by adding new functions are a bit of a grey area. It's better to consult the community, because there may be useful feedback about (say) the order of arguments, or the name of the function, or whatnot. On the other hand few clients will actually break if you add a new function to the API. Use your judgment.

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

Controversial decisions

It's impossible to record all possible forms of a controversial decision. Here are some basic guidelines:

  • Adding a new, useful function under a clear name is probably not controversial
  • Breaking the API in any way is almost certainly controversial
  • Changing the semantics of an existing function is almost certainly controversial
  • Changes affecting Prelude and the Haskell Report are almost certainly controversial

It is important that, at the very least, the CLC receives an email on this topic. The individual maintainer is still in charge of the issue, but should give the CLC a chance to express an opinion. If after a reasonable amount of time (let's say one week) no objections are raised, the maintainer should feel free to move ahead with the change.

The CLC should repeat this decision making process again with more controversial issues. The prime example of this was the "burning bridges proposal": a change which drastically impacts Prelude should almost certainly be elevated to the libraries@ mailing list. Anything going to libraries@ should have at least a two week deadline on it.

At the end of the day, the CLC is still the body with decision making power. Explicitly: no single person should ever have veto power on a change. That includes the library maintainer; if the CLC votes against the library maintainer, that decision will stand. The CLC may itself decide to request support from others to make a decision, but is never required to do so.

Library Adoption

If a library reaches a critical mass (becomes so important to the community, it can be seen as core), the CLC should make efforts to adopt that library, coordinating with library maintainers.

The procedure for doing so is roughly:

  • CLC recognises a library not in LIBRARIES as core
  • Reach out to the maintainer(s) of the recognised package about migrating its ownership to CLC, keeping the existing maintainer(s).
  • If they are cooperative, the library will become a part of LIBRARIES, and all things that apply to LIBRARIES and CLC as per this document will apply to that library.
  • If they are not cooperative, CLC will respect the rights of maintainers, and allow the package to remain separate. However, CLC should be encouraged to contribute to that package going forward, and co-maintain if possible.

There are some clear candidates for adoption:

  • text
  • bytestring
  • containers
  • unordered-containers
  • pretty
  • time

These are all packages which are "core" in that they ship with GHC and/or have reached critical mass, but are not currently owned by the CLC).

Haskell Library Report

CLC is tasked with updating and defining the part of the Haskell Language Report concerning the `base` library.

There is a pretty clear breakdown of this issue and some discussion here: https://groups.google.com/g/haskell-core-libraries/c/2malEk5df6A/m/a3cpqQANCgAJ, which should eventually be folded into this page.

Retrieved from "https://wiki.haskell.org/index.php?title=Core_Libraries_Committee&oldid=63380"