Changes between Version 4 and Version 5 of AddingPackages

Show
Ignore:
Timestamp:
08/23/09 21:17:41 (5 years ago)
Author:
duncan (IP: 79.70.199.148)
Comment:

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

Legend:

Unmodified
Added
Removed
Modified
  • AddingPackages

    v4 v5  
    2222 * The Haskell Platform release team 
    2323 
     24Only the first half of this page is essential reading. 
     25 
    2426Structure of this document: 
    2527 
    26  * The [#Procedure procedure] and [#PackageRequirements package requirements] sections below define the policy. 
     28 * The [#Procedure procedure] and [#PackageRequirements package requirements] sections define the policy. 
    2729 * The [#Rationale rationale] section gives an explanation and justification for the policy. 
     30 * The [#Consensus consensus] section describes a procedure to help the decision making process. 
     31 
     32Related documents: 
     33 
    2834 * The "[#Howtoproposeanewpackage how to]" page gives practical advice on how to go about proposing a package. This is an "implementors guide" for the policy sections. 
    29  * The [#Consensus consensus] section describes a procedure to help the decision making process. 
     35 * There is an [wiki:Proposals/example example proposal]. 
    3036 
    3137The terms "must", "should" and "may" have their usual meanings from [http://www.ietf.org/rfc/rfc2119.txt RFC 2119]. 
     
    3339= Procedure = 
    3440 
    35 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 note-1.1]] 
    36  
    37 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 note-1.2]] 
    38  
    39 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 note-1.3]] 
    40  
    41 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 note-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). [[#RationaleProcedure 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.  [[#RationaleProcedure 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.  [[#RationaleProcedure 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). [[#RationaleProcedure rationale-1.4]] 
    4248 
    4349== Reviewers == 
    4450 
    45 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 note-2.1]] 
    46  
    47 Reviewers are encouraged to: [[#RationaleReviewers note-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]). [[#RationaleReviewers rationale-2.1]] 
     52 
     53Reviewers are encouraged to: [[#RationaleReviewers rationale-2.2]] 
    4854 * read the proposal 
    4955 * review material the proposal links to 
     
    5763== Updating the proposal == 
    5864 
    59 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 note-3.1]] 
    60  
    61 Open issues and objections raised by reviewers should be tracked on the proposal wiki under a separate section. [[#RationaleUpdatingProposal note-3.2]] 
     65The 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]] 
     66 
     67Open issues and objections raised by reviewers should be tracked on the proposal wiki under a separate section. [[#RationaleUpdatingProposal rationale-3.2]] 
    6268 
    6369The 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). 
    6470 
    65 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 note-3.3]] 
     71It 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]] 
    6672 
    6773== Deadlines == 
     
    6975Within each major release cycle there are two deadlines concerning package proposals: 
    7076 
    71  * 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 note-4.1]] 
    72  * A deadline for discussion on proposals for the next major release. [[#RationaleDeadlines note-4.2]] 
    73  
    74 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 note-4.3]] 
     77 * 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]] 
     78 * A deadline for discussion on proposals for the next major release. [[#RationaleDeadlines rationale-4.2]] 
     79 
     80The 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]] 
    7581 
    7682== Acceptance == 
    7783 
    78 A package is considered as accepted if, by the discussion deadline, the libraries mailing list reach consensus to accept it. [[#RationaleAcceptance note-5.1]] 
    79  
    80 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 note-5.2]] 
    81  
    82 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 note-5.3]] 
    83  
    84 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 note-5.4]] 
    85  
    86 The release team should work with the maintainers of accepted and conditionally accepted packages to include the package into the next major release. [[#RationaleAcceptance note-5.5]] 
    87  
    88 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 note-5.6]] 
     84A package is considered as accepted if, by the discussion deadline, the libraries mailing list reach consensus to accept it. [[#RationaleAcceptance rationale-5.1]] 
     85 
     86A 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]] 
     87 
     88Note 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]] 
     89 
     90The 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]] 
     91 
     92The 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]] 
     93 
     94After 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]] 
    8995 
    9096== Rejection == 
    9197 
    92 If consensus is not achieved by the discussion deadline then the package is not accepted for the next major release. [[#RationaleRejection note-6.1]] 
    93  
    94 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 note-6.2]] 
    95  
    96 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 note-6.3]] 
     98If consensus is not achieved by the discussion deadline then the package is not accepted for the next major release. [[#RationaleRejection rationale-6.1]] 
     99 
     100If 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]] 
     101 
     102A 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]] 
    97103 
    98104 
     
    101107The structure of the proposal is not prescribed, however it should cover the following points: 
    102108 
    103  * 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 note-7.1]] 
    104  
    105  * 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 note-7.2]] 
    106  
    107  * The major design decisions should be described and motivated where appropriate. [[#RationaleProposalContent note-7.3]] 
    108  
    109  * For library packages, an example of how the API is intended to be used should be given. [[#RationaleProposalContent note-7.4]] 
    110  
    111  * 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 note-7.5]] 
    112  
    113  * 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 note-7.6]] 
     109 * 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]] 
     110 
     111 * 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]] 
     112 
     113 * The major design decisions should be described and motivated where appropriate. [[#RationaleProposalContent rationale-7.3]] 
     114 
     115 * For library packages, an example of how the API is intended to be used should be given. [[#RationaleProposalContent rationale-7.4]] 
     116 
     117 * 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]] 
     118 
     119 * 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]] 
    114120 
    115121Where appropriate, existing sources of information about the package may be copied or linked to. No length requirements are given. 
     
    119125Every package should fulfil the following requirements. 
    120126 
    121  * Use the Cabal package format. [[#RationalePackageRequirements note-8.1]] 
    122  * Be distributed from Hackage. [[#RationalePackageRequirements note-8.2]] 
    123  * Library packages should have Haddock API documentation for all exported functions and types. [[#RationalePackageRequirements note-8.3]] 
    124  * Compile on all operating systems and compilers that the platform targets. [[#RationalePackageRequirements note-8.4]] 
    125  * Any Haskell packages that the package depends on must also be in the platform. [[#RationalePackageRequirements note-8.5]] 
    126  * Follow the [http://haskell.org/haskellwiki/Package_versioning_policy Package Versioning Policy] [[#RationalePackageRequirements note-8.6]] 
    127  
    128 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 note-8.7]] 
     127 * Use the Cabal package format. [[#RationalePackageRequirements rationale-8.1]] 
     128 * Be distributed from Hackage. [[#RationalePackageRequirements rationale-8.2]] 
     129 * Library packages should have Haddock API documentation for all exported functions and types. [[#RationalePackageRequirements rationale-8.3]] 
     130 * Compile on all operating systems and compilers that the platform targets. [[#RationalePackageRequirements rationale-8.4]] 
     131 * Any Haskell packages that the package depends on must also be in the platform. [[#RationalePackageRequirements rationale-8.5]] 
     132 * Follow the [http://haskell.org/haskellwiki/Package_versioning_policy Package Versioning Policy] [[#RationalePackageRequirements rationale-8.6]] 
     133 
     134This 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]] 
    129135 
    130136It is expected that the list of requirements will be adjusted over time by further agreement of the libraries list. 
     
    138144== Procedure == #RationaleProcedure 
    139145 
    140 [[#Procedure note-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. 
    141  
    142 [[#Procedure note-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). 
     146[[#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. 
     147 
     148[[#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). 
    143149 
    144150Having 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. 
    145151 
    146 [[#Procedure note-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. 
    147  
    148 [[#Procedure note-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. 
     152[[#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. 
     153 
     154[[#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. 
    149155 
    150156 
    151157== Reviewers == #RationaleReviewers 
    152158 
    153 [[#Reviewers note-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). 
    154  
    155 [[#Reviewers note-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. 
     159[[#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). 
     160 
     161[[#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. 
    156162 
    157163 
    158164== Updating the proposal == #RationaleUpdatingProposal 
    159165 
    160 [[#Updatingtheproposal note-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. 
     166[[#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. 
    161167 
    162168In 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. 
    163169 
    164 [[#Updatingtheproposal note-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. 
    165  
    166 [[#Updatingtheproposal note-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. 
     170[[#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. 
     171 
     172[[#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. 
    167173 
    168174 
    169175== Deadlines == #RationaleDeadlines 
    170176 
    171 [[#Deadlines note-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). 
    172  
    173 [[#Deadlines note-4.2]] Since the platform uses time-based releases there must be a deadline for when decisions on new packages must be made. 
    174  
    175 [[#Deadlines note-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. 
     177[[#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). 
     178 
     179[[#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. 
     180 
     181[[#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. 
    176182 
    177183 
    178184== Acceptance == #RationaleAcceptance 
    179185 
    180 [[#Acceptance note-5.1]] The package must be accepted before the deadline to give the release team enough time to integrate the package into the platform. 
    181  
    182 [[#Acceptance note-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). 
    183  
    184 [[#Acceptance note-5.3]] This is just a clarification of the meaning of acceptance. 
    185  
    186 [[#Acceptance note-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. 
    187  
    188 [[#Acceptance note-5.5]] Making a release is a cooperative effort between the release team and the maintainers of the platform packages. 
    189  
    190 [[#Acceptance note-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. 
     186[[#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. 
     187 
     188[[#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). 
     189 
     190[[#Acceptance rationale-5.3]] This is just a clarification of the meaning of acceptance. 
     191 
     192[[#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. 
     193 
     194[[#Acceptance rationale-5.5]] Making a release is a cooperative effort between the release team and the maintainers of the platform packages. 
     195 
     196[[#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. 
    191197 
    192198 
    193199== Rejection == #RationaleRejection 
    194200 
    195 [[#Rejection note-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. 
    196  
    197 [[#Rejection note-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. 
    198  
    199 [[#Rejection note-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. 
     201[[#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. 
     202 
     203[[#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. 
     204 
     205[[#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. 
    200206 
    201207 
    202208== Proposal content == #RationaleProposalContent 
    203209 
    204 [[#Proposalcontent note-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. 
    205  
    206 [[#Proposalcontent note-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. 
    207  
    208 [[#Proposalcontent note-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. 
    209  
    210 [[#Proposalcontent note-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. 
    211  
    212 [[#Proposalcontent note-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. 
    213  
    214 [[#Proposalcontent note-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. 
     210[[#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. 
     211 
     212[[#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. 
     213 
     214[[#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. 
     215 
     216[[#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. 
     217 
     218[[#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. 
     219 
     220[[#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. 
    215221 
    216222 
    217223== Package requirements == #RationalePackageRequirements 
    218224 
    219 [[#Packagerequirements note-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. 
    220  
    221 [[#Packagerequirements note-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. 
    222  
    223 [[#Packagerequirements note-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. 
    224  
    225 [[#Packagerequirements note-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. 
    226  
    227 [[#Packagerequirements note-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". 
    228  
    229 [[#Packagerequirements note-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. 
    230  
    231 [[#Packagerequirements note-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. 
     225[[#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. 
     226 
     227[[#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. 
     228 
     229[[#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. 
     230 
     231[[#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. 
     232 
     233[[#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". 
     234 
     235[[#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. 
     236 
     237[[#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. 
    232238 
    233239