Version 5 (modified by duncan, 5 years ago)

make clear which bits are essential reading and change [note-x.y] links to [rationale-x.y] to improve clarity

This is a draft policy document and has not yet been agreed by the libraries list. Certain parts only makes sense once it has been agreed.

Procedure for adding new packages

Introduction

The Haskell Platform is a standard Haskell distribution for every system. It provides a set of libraries and tools that are "blessed" by the Haskell community. This document sets out the community decision making process for adding new packages to this standard distribution.

The policy described here is the consensus of the Haskell libraries mailing list [link to mailing list thread]. It may be amended by further agreement of the libraries mailing list.

Who should read this:

  • People who want to propose a new package;
  • People reviewing proposed packages;
  • The Haskell Platform release team

Only the first half of this page is essential reading.

Structure of this document:

Related documents:

  • The "how to" page gives practical advice on how to go about proposing a package. This is an "implementors guide" for the policy sections.
  • There is an example proposal.

The terms "must", "should" and "may" have their usual meanings from RFC 2119.

Procedure

All packages in the platform must have a maintainer (or maintainers). The package maintainer(s) may propose a package for inclusion or they may delegate the task to someone else. In either case, proposals for inclusion must have the support of the package maintainer(s). [rationale-1.1]

The procedure involves an iterative effort between the people proposing a package (the "proposer(s)") and people from the libraries mailing list (the "reviewers"). The final decision to accept a package is based on a process of consensus amongst the reviewers. The procedure starts with the proposer(s) making a written proposal. This initial proposal must be added to the haskell-platform wiki and it must also be posted to the libraries mailing list for review. [rationale-1.2]

The proposal forms the nub of the argument for why the package should be included in the Haskell Platform. It should contain or link to enough information so that reviewers can make an informed decision on whether the package should be accepted. Further details on the content of the proposal are given below. The proposal wiki page is also used to track the status of the proposal and any final decision. [rationale-1.3]

A proposal may cover more than one package if those packages form a closely related unit (such as a system with multiple backends or extensions). [rationale-1.4]

Reviewers

The review process is open to all subscribers of the libraries mailing list. Participation in the review process is encouraged. Reviewers will be credited in the final versions of proposals (see acceptance). [rationale-2.1]

Reviewers are encouraged to: [rationale-2.2]

  • read the proposal
  • review material the proposal links to
  • ask questions about the package
  • make suggestions about the package
  • make suggestions about the proposal document
  • share experience of using the package
  • raise objections
  • come to view on whether the package should be accepted, either as-is or with certain modifications

Updating the proposal

The wiki version of the proposal is a live document which should reflect the latest changes accepted by the proposer(s). As agreement is reached on particular design issues, the proposer(s) should update the proposal to reflect the current accepted design. It is not required that the package implementation be immediately updated to keep it in sync with changes in the proposal. As a help to reviewers, the proposal may be updated to indicate significant points where the current proposal differs from the current package implementation. [rationale-3.1]

Open issues and objections raised by reviewers should be tracked on the proposal wiki under a separate section. [rationale-3.2]

The initial proposal email should link to the wiki version so that reviewers can always find a complete account of the current proposal (rather than having to re-read a full mailing list discussion thread).

It is the proposer(s), not the reviewers, who are in charge of updates to the proposal, including recording open issues and objections. In contentious cases, members of the steering committee may assist in recording reviewers concerns and objections in the proposal wiki.[rationale-3.3]

Deadlines

Within each major release cycle there are two deadlines concerning package proposals:

  • A deadline for proposals to be submitted for consideration for the next major release. Packages may be proposed at any time but this deadline is the cut-off date for inclusion into the next major release. Proposals missing this date are candidates for the subsequent major release. [rationale-4.1]
  • A deadline for discussion on proposals for the next major release. [rationale-4.2]

The exact dates are set by the release team with the aim of giving enough time to integrate new packages before a release and giving enough time to discuss new packages. The release team should announce and publicise these dates sufficiently far in advance. [rationale-4.3]

Acceptance

A package is considered as accepted if, by the discussion deadline, the libraries mailing list reach consensus to accept it. [rationale-5.1]

A package is considered as conditionally accepted if, by the discussion deadline, the libraries mailing list reaches consensus to accept it on condition that further minor changes are made. The agreed changes must be made before the package is included in any release. If these changes are made in time for the normal package freeze dates (as set by the release team) then the package is considered as accepted. If the changes cannot be made in time for the immediate major release but are made in time for the subsequent major release then the package is considered as accepted for that subsequent major release and does not need to be re-reviewed. [rationale-5.2]

Note that the required consensus is a consensus around the final version of the proposal, including updates made during the review process. For example if reviewers request changes and the proposers(s)/maintainers(s) are able to make those changes and consensus is reached by the deadline then the package can be accepted. [rationale-5.3]

The standard of consensus required is the same as that defined for the existing library submissions process. [rationale-5.4]

The release team should work with the maintainers of accepted and conditionally accepted packages to include the package into the next major release. [rationale-5.5]

After a proposal is accepted (or conditionally accepted) the proposal must remain on the wiki. It should be updated to record the decision and link to the email thread(s) that indicate that consensus was achieved. It should also be updated with a section giving credit to the individuals who contributed to the review process. These updates may be done by the proposer(s), members of the release team or members of the steering committee. [rationale-5.6]

Rejection

If consensus is not achieved by the discussion deadline then the package is not accepted for the next major release. [rationale-6.1]

If a proposal is not accepted then the proposal should remain on the wiki. It should be updated to record the decision (or lack thereof). If reviewers have indicated that they would support the proposal if certain changes are made then this should be recorded. [rationale-6.2]

A proposal may be re-submitted for a subsequent release cycle. The maintainer(s) and author(s) of the new proposal should take into account the feedback from the review of the previous proposal that was not accepted. A re-submitted proposal should be updated to clearly indicate the changes that have been made since the previous time the package was reviewed. [rationale-6.3]

Proposal content

The structure of the proposal is not prescribed, however it should cover the following points:

  • The proposal should state the author(s) of the proposal and the primary maintainer(s) of the package. Duplication is not required in the case that the proposal author(s) are the same as the primary maintainer(s). [rationale-7.1]
  • It should explain the gap in the existing set of platform packages that the new package addresses. Alternatively if the package would duplicate or replace any existing platform packages then the reasons why the new package is better should be clearly explained. In this case the proposal should be tied to another proposal to deprecate the existing package(s) (or parts thereof) and thought should be given to how the transition should be managed. [rationale-7.2]
  • The major design decisions should be described and motivated where appropriate. [rationale-7.3]
  • For library packages, an example of how the API is intended to be used should be given. [rationale-7.4]
  • Any dependency of one proposal on another should be noted explicitly. In particular a proposal to add a package may depend on another such proposal if the corresponding packages depend on each other. [rationale-7.5]
  • An explicit checklist of the package requirements below is not required. The proposal should state however that all the requirements are met, or for any requirements that are not met, a reason why they are not met. [rationale-7.6]

Where appropriate, existing sources of information about the package may be copied or linked to. No length requirements are given.

Package requirements

Every package should fulfil the following requirements.

This list of requirements is not exclusive. There is no guarantee that a package meeting all these requirements will be accepted (the condition of acceptance is given above). [rationale-8.7]

It is expected that the list of requirements will be adjusted over time by further agreement of the libraries list.

Interim license policy

A policy for the set of acceptable licenses has not yet been agreed by the community. Until such a policy is agreed the default position is that no new licenses can be accepted into the platform. The current set of licenses is just the BSD3 license. The implication is that until a license policy is agreed, proposed packages must use the BSD3 license.

Rationale

Procedure

[rationale-1.1] There is inevitably some ongoing maintenance work for each package. The platform release team cannot be expected to pick up maintenance of platform packages; it is not their job and it would not scale. We therefore require that each package has a commitment from its own maintainer(s). Dedicated maintainers are also in a better position to address bug reports and make improvements to the package. It is fine for the maintainer(s) to get help with the proposal process but they must support the proposal and by implication be prepared to maintain the package once it is in the platform.

[rationale-1.2] The platform is supposed to have the support of the community and serve its needs. Instead of having a small committee decide on which packages are in the platform, the process is open to all interested individuals via the libraries mailing list. This is like the existing library submissions process. It avoids the problem of how to pick some smaller group and brings a wider range of experience to the decision process. In particular it enables participation from community members with expertise in a particular problem domain or direct practical experience with using a proposed package (or one of its alternatives).

Having a discussion on the mailing list ensures that members of the community can make informed decisions. In addition to simply making a yes/no decision, a review process can often help to improve the quality of a package.

[rationale-1.3] The focus of the review process is around the package. Using a proposal is a simple device to have proposer(s) clearly present their argument and to give reviewers a starting point for finding the information they need to be able to review the package. The proposal wiki document is also a place to track other information related to the proposal where it can be found easily.

[rationale-1.4] For a set of packages that form one logical system, it may be easier to propose and review them together, especially if there would be significant overlap between separate proposals. The main judgement on whether to treat related packages in one proposal or separate proposals should be on what makes the review simpler and easier.

Reviewers

[rationale-2.1] A disadvantage of having the review process be open to everyone is that we cannot require anyone to actually spend the effort to do any review. One way to encourage review is to raise its status by giving prominent credit to reviewers. This simple idea has been tried with limited success in other open source communities (such as the Linux kernel developer community).

[rationale-2.2] Thorough review is important for the quality of the platform. Entry into the platform is an excellent time to receive feedback on the package itself and on how it fits with other packages in the platform. Thus we want to encourage as many reviewers as possible to review the package in depth.

Updating the proposal

[rationale-3.1] A problem with mailing list discussions about a document is that it can sometimes be hard to get a clear view about which changes have been accepted, especially for people who are late to join the discussion. By keeping the latest version in a wiki page this problem can be avoided. On the other hand a wiki is not suited to conversations. By using a combination of a mailing list discussion for detailed review and a wiki page to record the latest version, it is hoped to get the best of both mediums.

In addition, updating the proposal during the review period helps to ensure that issues raised by reviewers are not forgotten. It is expected that outstanding issues are taken into account by reviewers in their final decision to accept a package or not.

[rationale-3.2] Not all issues or objections raised by reviewers can or should be addressed immediately. To ensure that such suggestions are not forgotten, it is important that they are tracked somewhere. A section of the proposal is an obvious place to do so. This also lets other reviewers quickly see which issues have already been raised.

[rationale-3.3] The proposer(s) have authorship of the proposal and it is right that they retain that authorship, even over the wiki version of the proposal. This should also prevent confusion over who is responsible for making updates, or confusion over what changes have actually been accepted (as might be the case if reviewers also directly edited the wiki document). While members of the steering committee may assist in recording concerns and updating the status after acceptance, these modifications to the wiki document are be limited to the "open issues" (or equivalent) section and so they do not affect the authorship of the main body of the proposal.

Deadlines

[rationale-4.1] Reviewers need a reasonable amount of time to properly review packages. Since there is a cut-off for when decisions must be made, there must also be a cut-off for when proposals must be submitted otherwise there would not be enough time to review packages properly. On the other hand there is no earliest point when proposals can be submitted, this allows for an extended review period at the discretion of the proposer(s).

[rationale-4.2] Since the platform uses time-based releases there must be a deadline for when decisions on new packages must be made.

[rationale-4.3] It is the release team that are in charge of organising the release timetable (though the overall length of the release cycle is based on a decision of the libraries list). These two deadlines are part of the release timetable and thus it makes sense for the release team to set them.

Acceptance

[rationale-5.1] The package must be accepted before the deadline to give the release team enough time to integrate the package into the platform.

[rationale-5.2] The notion of conditional acceptance is for practicality. It allows decisions to be made near the deadline while deferring minor changes until after the deadline (but before the other normal package freeze deadlines).

[rationale-5.3] This is just a clarification of the meaning of acceptance.

[rationale-5.4] The exact definition of what constitutes a consensus is possibly a contentious point. The obvious choice is to do what we already do with the existing library submissions process. It uses a relatively vague definition of consensus and yet has worked reasonably well in practice. If it does not work out in practice for the package addition process then the libraries list may want to revisit this point.

[rationale-5.5] Making a release is a cooperative effort between the release team and the maintainers of the platform packages.

[rationale-5.6] Package proposals are also intended to serve as a permanent record of why a package was accepted into the platform. It is also the obvious place to give credit to the author(s) of the proposal and the reviewers of the package. We wish to give these people credit because they have put it volunteer effort for the benefit of the community.

Rejection

[rationale-6.1] Packages should not be accepted until the reviewers have reached consensus to make sure issues are addressed and that the package has the general support of the community.

[rationale-6.2] By preserving the proposal on the wiki developers curious about why a proposal was rejected can read the rationale for the rejection and review the the remaining open issues.

[rationale-6.3] It is expected that for some packages reviewers may request more significant changes. The intention is to encourage those packages to be improved and resubmitted. On the other hand, old decisions should only be reconsidered when there is new information that might change the old decision. This is to avoid wasting time reiterating the same arguments that led to the old decision.

Proposal content

[rationale-7.1] Listing the author and maintainer is useful simply as contact information for the release team or future readers. The maintainer should be listed as an indication that they are signing up to support the package and its inclusion in the platform. The latter is particularly relevant when they are not one of the authors of the proposal. The proposal author should also be listed to indicate that the document does indeed have an author who will take responsibility for updating it. Also, the proposal author deserves credit for the effort they put in.

[rationale-7.2] To avoid user confusion and reduce the maintenance burden, we wish to avoid having several packages provide the same or significantly overlapping functionality. It is fine to provide packages that solve the same problem but provide significantly different or complementary approaches.

[rationale-7.3] Since the reviewers are all volunteers, and outnumber the proposers, it makes sense to require the proposers to do a small amount of extra work to ease the job of the reviewers. By making the review process as easy as possible more people are likely to review the proposal.

[rationale-7.4] API reference documentation is not always enough to understand how an API is intended to be used. By giving a few common use cases, reviewers may better understand the API and may be able to review it more easily.

[rationale-7.5] Reviewers need to be aware if there are dependencies between proposals so that they know that one proposal cannot be accepted without accepting the other.

[rationale-7.6] Asking for the proposal to mention that the package does meet all the package requirements may feel redundant but it serves as a reminder to the proposal author to double-check that it does so. The package requirements are an important part of the criteria for adding a package. There needs to be pretty good reasons for any requirements that are not met and those reasons should be explained.

Package requirements

[rationale-8.1] As a matter of practicality all packages need to use the Cabal package format. This is because the release team use automated tools to manage the platform release. Similarly most distro packaging people use similar tools to automate the translation of Cabal packages to native distro packages. The release team and the distro packaging teams can only manage reasonable numbers of packages by using these automation tools.

[rationale-8.2] Is it important that each platform package can be obtained from a single Hackage server. Note that this is not an exclusive requirement: it is fine for platform packages to be distributed from multiple sources but they must at least be distributed from hackage. One reason is that it is intended that the platform meta-package be distributed from Hackage which would enable end-users to upgrade the platform version via the 'cabal' tool, but this can only be automated if all the platform packages are available on Hackage. In addition Hackage provides a common infrastructure that the release team can use when making a release. Being available from Hackage also makes it easier for reviewers to install the package for testing.

[rationale-8.3] API reference documentation is necessary to ensure that package is usable once it is included in the platform. It is also needed by the reviewers to understand the intended functionality of the package.

[rationale-8.4] The platform is intended to work on number of operating systems and thus all packages that make up the platform must work on the set of supported operating systems.

[rationale-8.5] Part of the definition of the platform is that it is self-contained, meaning packages in the platform can only depend on other packages in the platform. It may seem that it might be possible to allow shipping packages that are somehow "not blessed" as being part of the platform, however there is currently no obvious way to make a practical distinction between "blessed" and "not blessed".

[rationale-8.6] Since the platform follows the package versioning policy, it makes sense for its constituent packages to do so. This makes it easier for the release team to work out which package updates are eligible to be included in upcoming major and minor releases.

[rationale-8.7] The purpose of the list of requirements is not to give a complete set of requirements. Instead it is there to codify minimum requirements so that proposers know what is expected before making a proposal and asking for feedback. The list may also serve to give some degree of consistency in the quality standards asked for by reviewers.

Achieving consensus

The decision making process we use is open to all interested individuals and it calls for "consensus".

Making decisions by consensus relies on:

  • respect and trust;
  • recognising that we share common goals and principles;
  • being prepared to listen and to participate.

This section explains a protocol that we will be trying out that we hope will help us in the more contentious cases.

For more background see these notes on consensus for free software projects and on formal consensus in general. The protocol described here is a lightweight, customised version of the formal consensus process.

A protocol for consensus

The protocol involves a series of stages of discussion on the libraries mailing list. At each stage there is a "call for consensus" from a member steering committee. If there is consensus then we are done. If not, then we move to the next stage.

  1. The first stage is presenting the proposal followed by open group discussion. This stage lasts long enough to give everyone the opportunity to send in their review comments. There follows a call for consensus.
  2. The second stage starts by listing concerns, combining related concerns and recording them on the proposal's wiki page. Then there is further discussion to try to resolve the listed concerns. Again we have a call for consensus.
  3. The last stage requires the remaining concerns be restated and questions should be asked to clarify those concerns. The proposal wiki page is updated with the details of the remaining concerns. At this stage discussion should be limited to resolving one concern at a time. We end with a final call for consensus.

A call for consensus is an email from a member of the steering committee asking "Are there any unresolved concerns?". In the case that we are attempting to achieve consensus for conditional acceptance, the email should detail the conditions.

People who participate in the review process for a package are expected to participate in the call for consensus.

Each time there is a call for consensus, everyone has three options:

  • Say nothing. This indicates you're prepared to accept the current proposal.
  • Stand aside. An email to say that you do have unresolved concerns but you are prepared to see the proposal accepted. These concerns should be recorded in the proposal.
  • Raise objection. Objections need accompanying reasoning so that others can try to work with that reasoning to find a resolution to the issue. Especially in later stages, objections must be argued from the basis of community goals and principles. Objections should be recorded in the proposal.

The final outcome then is either consensus (possibly with some people having stood aside) or we must declare a block.

Timing issues:

  • The initial stage needs to be long enough to give all reviewers an opportunity to review the package and send in comments.
  • In the second stage, it makes sense to call for consensus as soon as a successful outcome seems likely or if it would help to move the discussion forward.
  • In the final stage, in the worst case, the final call for consensus may be at the same time as the final discussion deadline.
  • In each call for consensus, a reasonable time should be allowed for the participants to respond.
  • The overall process needs enough time to allow for going through all three stages. For example a 6 month release cycle might have a two month window to propose and agree package additions. It may make sense to split that time in half, the first to give everyone the chance to submit review comments, leaving the second month in case there are concerns that take a long time to discuss and resolve.

Recording and tracking of concerns:

  • In the first stage the proposer or a member of the steering committee can record concerns in the "open issues" (or equivalent) section of the proposal.
  • In the second and third stage, the steering committee member who does the call for consensus should record concerns.

This tracking of concerns in a section of the proposal's wiki page does not affect the authorship of the proposal in general.

Note that in an unfortunate case where a proposal gets no review comments, it would not be appropriate to issue a call for consensus because it could lead to an unreviewed package being accepted. Since participation in the review process implies participation in the call for consensus then we need at least some review comments to guarantee a meaningful call for consensus. In such a case the proposer and steering committee should make more noise on the mailing list about the proposal.

Advice on consensus

Here are some tips:

  • Focus on the proposal and avoid drifting off into tangential areas. Keep things concrete.
  • Make sure concerns are recorded (in the proposal) rather than silently ignored and forgotten.
  • Our goal is to give the greatest benefit to the community, not to achieve perfection.
  • Don't try to rush things through. We will end up with better software if things are given the time they need.
  • Be prepared to say what you think.
  • Be prepared to stand aside: accept a decision and have objections, concerns or TODOs recorded in the proposal.
  • Finally, to give everyone a chance to be heard, ask if anybody has further concerns rather than asking if everybody agrees.

Remember that a possible outcome is consensus for conditional acceptance.

In the worst case keep in mind that it is always possible to aim for a subsequent release. The Haskell Platform's major release cycles are not all that long.

History

As stated in the introduction, the policy described in this document may be amended by further agreement of the libraries mailing list. The current version you see above includes all the current amendments. This section lists the history of amendments that have been made, along with links to the mailing list threads where they were discussed and agreed.

  • The original version was written and reviewed by the steering committee: Adam Wick, Duncan Coutts, Iavor Diatchki, Isaac Dupree, Johan Tibell and Thomas Schilling.
  • There have not yet been any amendments.