Changes between Version 10 and Version 11 of AddingPackages

Show
Ignore:
Timestamp:
09/17/09 19:36:52 (5 years ago)
Author:
duncan (IP: 79.70.213.67)
Comment:

Remove the rationale section and link to the new rationale page

Legend:

Unmodified
Added
Removed
Modified
  • AddingPackages

    v10 v11  
    2222 * The Haskell Platform release team 
    2323 
    24 Only the first half of this page is essential reading. 
     24Only the first two sections of this page are essential reading. 
    2525 
    2626Structure of this document: 
    2727 
    2828 * The [#Procedure procedure] and [#PackageRequirements package requirements] sections define the policy. 
    29  * The [#Rationale rationale] section gives an explanation and justification for the policy. 
    3029 * The [#Consensus consensus] section describes a procedure to help the decision making process. 
     30 * The [wiki:AddingPackages/Rationale rationale] page gives an explanation and justification for the policy. 
    3131 
    3232Related documents: 
     
    3939= Procedure = 
    4040 
    41 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). [[#RationaleProcedure rationale-1.1]] 
    42  
    43 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 [#Acceptance accept] a package is based on a process of [#Consensus 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.  [[#RationaleProcedure rationale-1.2]] 
    44  
    45 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 given below]. The proposal wiki page is also used to track the status of the proposal and any final decision.  [[#RationaleProcedure rationale-1.3]] 
    46  
    47 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). [[#RationaleProcedure rationale-1.4]] 
     41All 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). [[wiki:AddingPackages/Rationale#Procedure rationale-1.1]] 
     42 
     43The 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 [#Acceptance accept] a package is based on a process of [#Consensus 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.  [[wiki:AddingPackages/Rationale#Procedure rationale-1.2]] 
     44 
     45The 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 given below]. The proposal wiki page is also used to track the status of the proposal and any final decision.  [[wiki:AddingPackages/Rationale#Procedure rationale-1.3]] 
     46 
     47A proposal may cover more than one package if those packages form a closely related unit (such as a system with multiple backends or extensions). [[wiki:AddingPackages/Rationale#Procedure rationale-1.4]] 
    4848 
    4949== Reviewers == 
    5050 
    51 The review process is open to all subscribers of the [http://www.haskell.org/mailman/listinfo/libraries libraries mailing list]. Participation in the review process is encouraged. Reviewers will be credited in the final versions of proposals (see [#Acceptance acceptance]). [[#RationaleReviewers rationale-2.1]] 
    52  
    53 Reviewers are encouraged to: [[#RationaleReviewers rationale-2.2]] 
     51The review process is open to all subscribers of the [http://www.haskell.org/mailman/listinfo/libraries libraries mailing list]. Participation in the review process is encouraged. Reviewers will be credited in the final versions of proposals (see [#Acceptance acceptance]). [[wiki:AddingPackages/Rationale#Reviewers rationale-2.1]] 
     52 
     53Reviewers are encouraged to: [[wiki:AddingPackages/Rationale#Reviewers rationale-2.2]] 
    5454 * read the proposal 
    5555 * review material the proposal links to 
     
    6464== Updating the proposal == 
    6565 
    66 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. [[#RationaleUpdatingProposal rationale-3.1]] 
     66The 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. [[wiki:AddingPackages/Rationale#UpdatingProposal rationale-3.1]] 
    6767 
    6868Open issues and objections raised by reviewers should be tracked on the proposal wiki under a separate section. [[#RationaleUpdatingProposal rationale-3.2]] 
     
    7070The 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). 
    7171 
    72 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 [wiki:Members#SteeringCommittee steering committee] may assist in recording reviewers concerns and objections in the proposal wiki.[[#RationaleUpdatingProposal rationale-3.3]] 
     72It 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 [wiki:Members#SteeringCommittee steering committee] may assist in recording reviewers concerns and objections in the proposal wiki.[[wiki:AddingPackages/Rationale#UpdatingProposal rationale-3.3]] 
    7373 
    7474== Deadlines == 
     
    7676Within each major release cycle there are two deadlines concerning package proposals: 
    7777 
    78  * 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. [[#RationaleDeadlines rationale-4.1]] 
    79  * A deadline for discussion on proposals for the next major release. [[#RationaleDeadlines rationale-4.2]] 
    80  
    81 The exact dates are set by the [wiki:Members#ReleaseTeam 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. [[#RationaleDeadlines rationale-4.3]] 
     78 * 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. [[wiki:AddingPackages/Rationale#Deadlines rationale-4.1]] 
     79 * A deadline for discussion on proposals for the next major release. [[wiki:AddingPackages/Rationale#Deadlines rationale-4.2]] 
     80 
     81The exact dates are set by the [wiki:Members#ReleaseTeam 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. [[wiki:AddingPackages/Rationale#Deadlines rationale-4.3]] 
    8282 
    8383== Acceptance == 
    8484 
    85 A package is considered as accepted if, by the discussion deadline, the reviewers reach consensus to accept it. [[#RationaleAcceptance rationale-5.1]] 
    86  
    87 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. [[#RationaleAcceptance rationale-5.2]] 
    88  
    89 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. [[#RationaleAcceptance rationale-5.3]] 
    90  
    91 The standard of consensus required is the same as that defined for the existing [http://www.haskell.org/haskellwiki/Library_submissions#At_the_end_of_the_discussion_period library submissions process]. [[#RationaleAcceptance rationale-5.4]] 
    92  
    93 The release team should work with the maintainers of accepted and conditionally accepted packages to include the package into the next major release. [[#RationaleAcceptance rationale-5.5]] 
    94  
    95 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. [[#RationaleAcceptance rationale-5.6]] 
     85A package is considered as accepted if, by the discussion deadline, the reviewers reach consensus to accept it. [[wiki:AddingPackages/Rationale#Acceptance rationale-5.1]] 
     86 
     87A 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. [[wiki:AddingPackages/Rationale#Acceptance rationale-5.2]] 
     88 
     89Note 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. [[wiki:AddingPackages/Rationale#Acceptance rationale-5.3]] 
     90 
     91The standard of consensus required is the same as that defined for the existing [http://www.haskell.org/haskellwiki/Library_submissions#At_the_end_of_the_discussion_period library submissions process]. [[wiki:AddingPackages/Rationale#Acceptance rationale-5.4]] 
     92 
     93The release team should work with the maintainers of accepted and conditionally accepted packages to include the package into the next major release. [[wiki:AddingPackages/Rationale#Acceptance rationale-5.5]] 
     94 
     95After 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. [[wiki:AddingPackages/Rationale#Acceptance rationale-5.6]] 
    9696 
    9797== Rejection == 
    9898 
    99 If consensus is not achieved by the discussion deadline then the package is not accepted for the next major release. [[#RationaleRejection rationale-6.1]] 
    100  
    101 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. [[#RationaleRejection rationale-6.2]] 
    102  
    103 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. [[#RationaleRejection rationale-6.3]] 
     99If consensus is not achieved by the discussion deadline then the package is not accepted for the next major release. [[wiki:AddingPackages/Rationale#Rejection rationale-6.1]] 
     100 
     101If 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. [[wiki:AddingPackages/Rationale#Rejection rationale-6.2]] 
     102 
     103A 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. [[wiki:AddingPackages/Rationale#Rejection rationale-6.3]] 
    104104 
    105105 
     
    108108The structure of the proposal is not prescribed, however it should cover the following points: 
    109109 
    110  * 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). [[#RationaleProposalContent rationale-7.1]] 
    111  
    112  * 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. [[#RationaleProposalContent rationale-7.2]] 
    113  
    114  * The major design decisions should be described and motivated where appropriate. [[#RationaleProposalContent rationale-7.3]] 
    115  
    116  * For library packages, an example of how the API is intended to be used should be given. [[#RationaleProposalContent rationale-7.4]] 
    117  
    118  * 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. [[#RationaleProposalContent rationale-7.5]] 
    119  
    120  * An explicit checklist of the [#Packagerequirements 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. [[#RationaleProposalContent rationale-7.6]] 
     110 * 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). [[wiki:AddingPackages/Rationale#ProposalContent rationale-7.1]] 
     111 
     112 * 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. [[wiki:AddingPackages/Rationale#ProposalContent rationale-7.2]] 
     113 
     114 * The major design decisions should be described and motivated where appropriate. [[wiki:AddingPackages/Rationale#ProposalContent rationale-7.3]] 
     115 
     116 * For library packages, an example of how the API is intended to be used should be given. [[wiki:AddingPackages/Rationale#ProposalContent rationale-7.4]] 
     117 
     118 * 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. [[wiki:AddingPackages/Rationale#ProposalContent rationale-7.5]] 
     119 
     120 * An explicit checklist of the [#Packagerequirements 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. [[wiki:AddingPackages/Rationale#ProposalContent rationale-7.6]] 
    121121 
    122122Where appropriate, existing sources of information about the package may be copied or linked to. No length requirements are given. 
     
    126126Every package should fulfil the following requirements. Any requirements that are not met must be clearly explained and justified in the proposal. 
    127127 
    128  * Use the Cabal package format. [[#RationalePackageRequirements rationale-8.1]] 
    129  * Be distributed from Hackage. [[#RationalePackageRequirements rationale-8.2]] 
     128 * Use the Cabal package format. [[wiki:AddingPackages/Rationale#PackageRequirements rationale-8.1]] 
     129 * Be distributed from Hackage. [[wiki:AddingPackages/Rationale#PackageRequirements rationale-8.2]] 
    130130 * Be distributed under an acceptable copyright license. See the [#Interimlicensepolicy interim license policy]. 
    131  * Library packages should have Haddock API documentation for all exported functions and types. [[#RationalePackageRequirements rationale-8.3]] 
    132  * Compile on all operating systems and compilers that the platform targets. [[#RationalePackageRequirements rationale-8.4]] 
    133  * Any Haskell packages that the package depends on must also be in the platform. [[#RationalePackageRequirements rationale-8.5]] 
    134  * Follow the [http://haskell.org/haskellwiki/Package_versioning_policy Package Versioning Policy] [[#RationalePackageRequirements rationale-8.6]] 
    135  
    136 This list of requirements is not exclusive. There is no guarantee that a package meeting all these requirements will be accepted (the [#Acceptance condition of acceptance] is given above). [[#RationalePackageRequirements rationale-8.7]] 
     131 * Library packages should have Haddock API documentation for all exported functions and types. [[wiki:AddingPackages/Rationale#PackageRequirements rationale-8.3]] 
     132 * Compile on all operating systems and compilers that the platform targets. [[wiki:AddingPackages/Rationale#PackageRequirements rationale-8.4]] 
     133 * Any Haskell packages that the package depends on must also be in the platform. [[wiki:AddingPackages/Rationale#PackageRequirements rationale-8.5]] 
     134 * Follow the [http://haskell.org/haskellwiki/Package_versioning_policy Package Versioning Policy] [[wiki:AddingPackages/Rationale#PackageRequirements rationale-8.6]] 
     135 
     136This list of requirements is not exclusive. There is no guarantee that a package meeting all these requirements will be accepted (the [#Acceptance condition of acceptance] is given above). [[wiki:AddingPackages/Rationale#PackageRequirements rationale-8.7]] 
    137137 
    138138It is expected that the list of requirements will be adjusted over time by further agreement of the libraries list. 
     
    141141 
    142142A 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. 
    143  
    144 = Rationale = 
    145  
    146 == Procedure == #RationaleProcedure 
    147  
    148 [[#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. 
    149  
    150 [[#Procedure 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 [http://haskell.org/haskellwiki/Library_submissions 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). 
    151  
    152 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. 
    153  
    154 [[#Procedure 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. 
    155  
    156 [[#Procedure 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. 
    157  
    158  
    159 == Reviewers == #RationaleReviewers 
    160  
    161 [[#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). 
    162  
    163 [[#Reviewers 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. 
    164  
    165  
    166 == Updating the proposal == #RationaleUpdatingProposal 
    167  
    168 [[#Updatingtheproposal 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. 
    169  
    170 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. 
    171  
    172 [[#Updatingtheproposal 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. 
    173  
    174 [[#Updatingtheproposal 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. 
    175  
    176  
    177 == Deadlines == #RationaleDeadlines 
    178  
    179 [[#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). 
    180  
    181 [[#Deadlines rationale-4.2]] Since the platform uses time-based releases there must be a deadline for when decisions on new packages must be made. 
    182  
    183 [[#Deadlines 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. 
    184  
    185  
    186 == Acceptance == #RationaleAcceptance 
    187  
    188 [[#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. 
    189  
    190 [[#Acceptance 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). 
    191  
    192 [[#Acceptance rationale-5.3]] This is just a clarification of the meaning of acceptance. 
    193  
    194 [[#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. 
    195  
    196 [[#Acceptance rationale-5.5]] Making a release is a cooperative effort between the release team and the maintainers of the platform packages. 
    197  
    198 [[#Acceptance 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. 
    199  
    200  
    201 == Rejection == #RationaleRejection 
    202  
    203 [[#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. 
    204  
    205 [[#Rejection 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. 
    206  
    207 [[#Rejection 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. 
    208  
    209  
    210 == Proposal content == #RationaleProposalContent 
    211  
    212 [[#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. 
    213  
    214 [[#Proposalcontent 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. 
    215  
    216 [[#Proposalcontent 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. 
    217  
    218 [[#Proposalcontent 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. 
    219  
    220 [[#Proposalcontent 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. 
    221  
    222 [[#Proposalcontent 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. 
    223  
    224  
    225 == Package requirements == #RationalePackageRequirements 
    226  
    227 [[#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. 
    228  
    229 [[#Packagerequirements 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. 
    230  
    231 [[#Packagerequirements 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. 
    232  
    233 [[#Packagerequirements 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. 
    234  
    235 [[#Packagerequirements 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". 
    236  
    237 [[#Packagerequirements 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. 
    238  
    239 [[#Packagerequirements 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. 
    240143 
    241144