AddingPackages Rationale

Rationale

This page gives an explanation and justification for the procedure for adding new packages.

It is not intended to be make sense as a standalone document. It should be read in the context of the policy. Each section of the policy is cross-linked to the explanation on this page and vice-versa.

=== Procedure === #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 === #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 === #UpdatingProposal

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

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

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.