Skip to content
This repository has been archived by the owner on Feb 3, 2022. It is now read-only.

AddingPackages

Jump to bottom
Robert M. Lefkowitz edited this page Jun 23, 2014 · 3 revisions

Table of Contents

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. It may be [#History] 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 two sections of this page are essential reading.

Structure of this document:

  • The [#Procedure] and [#Packagerequirements] sections define the policy.
  • The [#Consensus] section describes a procedure to help the decision making process.
  • The [AddingPackages-Rationale|rationale] page gives an explanation and justification for the policy.

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 == #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 [#Proposalcontent]. 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 a view on whether the package should be accepted, either as-is or with certain modifications
  • work with other reviewers to try to achieve a consensus view

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. #RationaleUpdatingProposal 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 === #Acceptance

A package is considered as accepted if, by the discussion deadline, the reviewers 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. [[AddingPackages-Rationale#ProposalContent|rationale-7.5]]
  • An explicit checklist of the [#Packagerequirements] 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.

If new documentation is written for the proposal that would be useful in future for users of the package (e.g. an introduction or tutorial) then we wish to ensure that it is indeed made available to users. In the case that useful new documentation is written, reviewers are strongly encouraged to make it a condition of acceptance that the new material be republished in the appropriate place and form (e.g. on a package's homepage or integrated into API reference documentation).

Package requirements

Every package should fulfil the following requirements. Any requirements that are not met must be clearly explained and justified in the proposal.

  • Use the Cabal package format. rationale-8.1
  • Be distributed from Hackage. rationale-8.2
  • Be distributed under an acceptable copyright license. See the [AddingPackages#InterimLicensePolicy|interim]].
  • Library packages should have Haddock API documentation for all exported functions and types. rationale-8.3
  • Compile on all operating systems and compilers that the platform targets. rationale-8.4
  • Any Haskell packages that the package depends on must also be in the platform. rationale-8.5
  • Follow the rationale-8.6

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 === #InterimLicensePolicy

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.

== Achieving consensus == #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 of the 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.

Clone this wiki locally