├── README.rst ├── inline-comment.png ├── proposals ├── 0000-proposal-process.rst └── 0000-template.rst └── rich-diff.png /README.rst: -------------------------------------------------------------------------------- 1 | Haskell Ecosystem Proposals 2 | ============================ 3 | 4 | This repository contains specifications for proposed changes to the 5 | broader haskell ecosystem. See the `Proposal 6 | Process Proposal 7 | `_ 8 | for a complete description of the ecosystem proposal process. 9 | 10 | It is shamelessly copied from the one used for `GHC Proposals `_ 11 | 12 | 13 | What is a proposal? 14 | ------------------- 15 | 16 | An Ecosystem Proposal is a document describing a proposed change to the Haskell Ecosystem. These 17 | include, 18 | 19 | * Interoperability between package managers (e.g. cabal-install/hackage and 20 | stack/stackage). 21 | 22 | * Anything else of broader interest to the community. 23 | 24 | This list is currently deliberately short to keep it simple and focussed, it can 25 | be expanded as we as a community gauge the receptiveness of the community to 26 | this process. 27 | 28 | How do I comment on a proposal? 29 | ------------------------------- 30 | 31 | Discussion on a proposal occurs on its associated pull request. Click on the 32 | Pull Requests tab in GitHub to see a listing of the proposals currently under 33 | discussion. To see the text of the proposal click on the "Files Changed" tab on 34 | corresponding Pull Request page. 35 | 36 | Github offers two ways of viewing diffs: the "source diff" view, which shows a 37 | plain text diff, and the "rich diff" view, which provides a more readable 38 | rendered view of the markup. The view can be selected using the buttons on the 39 | top-right corner of the "Files Changed" tab. 40 | 41 | .. figure:: rich-diff.png 42 | :alt: The view selector buttons. 43 | :align: right 44 | 45 | Use the view selector buttons on the top right corner of the "Files 46 | Changed" tab to change between "source diff" and "rich diff" views. 47 | 48 | Feedback on a proposal can be offered on open pull requests using both Github's 49 | in-line and pull request commenting features. Do note, however, that inline 50 | comments can only be added via the "source diff" view. 51 | 52 | .. figure:: inline-comment.png 53 | :alt: The ``+`` button appears while hovering over line in the source diff view. 54 | :align: right 55 | 56 | Hover over a line in the source diff view of a pull request and 57 | click on the ``+`` to leave an inline comment 58 | 59 | How do I submit a proposal? 60 | --------------------------- 61 | 62 | While the full process is described in the `proposal 63 | `_ describing the proposal 64 | process, here is a short summary, 65 | 66 | 1. Edit the `template 67 | `_ 68 | to reflect your proposal. Rename the template file according to your 69 | desired proposal, but leave the numerical prefix as ``0000``. 70 | This can be done either online through GitHub's in-place 71 | editing feature (the pencil icon visible when viewing a file on GitHub) 72 | or by forking this repository and cloning the fork. 73 | See GitHub's `documentation 74 | `_ if you are unfamiliar with 75 | this aspect of GitHub's workflow. 76 | 77 | 2. Write the proposal. At very least this should describe the following, 78 | 79 | a. *Motivation*: What is the problem that you are trying to solve? Be specific: 80 | a concrete example or two can do wonders. Be sure to point out the 81 | particular ways in which the status quo falls short. 82 | b. *Proposed Change*: What change are you proposing? This is the 83 | specification of your change and should be precise and comprehensive. This 84 | might include, 85 | 86 | * scope of the change, what does it affect? cabal? stack? a web site? 87 | * the intended operation of the new change 88 | * how the proposed change addresses the original problem 89 | (perhaps returning to the concrete examples introduced in the 90 | *Motivation* section). 91 | * how the proposed change might interact with existing ecosystem features. 92 | In particular, pay attention to any unintended effects outside the 93 | immediate scope of the particular change. 94 | 95 | This generally needn't discuss the implementation of the change. 96 | c. *Drawbacks*: There's no such thing as a free lunch; what is the cost of 97 | your proposal? This includes the cost of implementing the proposal, 98 | mainintaining it indefinitely, teaching it to new users, and considering 99 | its interaction with future proposals. 100 | d. *Alternatives*: What alternatives to the proposed change exist? These can 101 | range from minor variants to completely . This doesn't need to go into 102 | great detail, just give the reader a sketch of the design space. 103 | e. *Unresolved questions*: What issues area still outstanding in the design? 104 | This needn't discuss outstanding *implementation* questions, we are 105 | presently only concerned with the conceptual design of your idea. 106 | 107 | Note that proposals are written in `ReStructuredText 108 | `_ rather than Markdown for 109 | its expressiveness and ease of integration into other GHC infrastructure. 110 | See the `GHC Users Guide 111 | `_ 112 | for a brief introduction to ReStructuredText. 113 | 114 | 3. When you feel your proposal document is complete, push your branch to your 115 | fork (e.g. ``git push origin fancy-new-idea``), and open a Pull 116 | Request requesting that your branch be merged into the ``master`` branch of 117 | the ``haskell/ecosystem-proposals`` repository. If you unfamiliar with 118 | GitHub pull requests then see the `relevant documentation 119 | `_. 120 | 121 | Be sure to include a link to the rendered view of your proposal in the pull 122 | request description. Your proposal will automatically be announced on the 123 | ``TBD, probably haskell-cafe`` mailing list when this pull request is opened. 124 | 125 | 4. Discussion will proceed on the pull request; it is very likely that multiple 126 | iterations will be necessary before the proposal stabilizes. If your proposal 127 | involves changes in multiple projects, make sure that representatives of each 128 | project are involved in the discussion. 129 | 130 | 5. Unlike the GHC proposals process, there is no committee who will be 131 | responsible to approve or reject your proposal. This is because the ecosystem 132 | consists of many separate projects, and nobody has the authority to tell the 133 | contributors of those projects that they must now implement something because 134 | a committee has decided so. Instead, you need to get buy-in from 135 | representatives of each involved project. Once it is clear to you that they 136 | will go forward with the implementation, please add a comment stating that 137 | you consider your proposal accepted and one of the maintainers of this 138 | repository will mark it as accepted. 139 | -------------------------------------------------------------------------------- /inline-comment.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haskell/ecosystem-proposals/12c93a36d3aaa59ce746a7857ecb1a654c17ef68/inline-comment.png -------------------------------------------------------------------------------- /proposals/0000-proposal-process.rst: -------------------------------------------------------------------------------- 1 | A Proposal for Proposals 2 | ======================== 3 | 4 | .. contents:: 5 | 6 | Recently `GHC Proposals`_ was 7 | instituted, and seems to be a success, in giving all interested parties a voice 8 | in proposed changes to GHC. 9 | 10 | As there is a wider ecosystem around Haskell, in particular package curation, 11 | discovery and management, this proposal process is proposed to similarly provide 12 | a constructive venue for discussion around it. 13 | 14 | Note that this document is *proposing* a process, it is not describing some sort 15 | of official process for getting change to occur in the Haskell ecosystem. We are 16 | humbly proposing it to you, dear member of the Haskell community, as a way to 17 | rally forces around your ideas so that it gets done. Feel free to use a 18 | different process if you think it has a better chance of success. 19 | 20 | Motivation 21 | ---------- 22 | 23 | As Haskell has matured and started getting wider acceptance and use, the layer 24 | of ecosystem beyond the raw compiler has started to receive attention. 25 | 26 | In particular, there are now at least two end user package management tools, 27 | `cabal-install` and `stack`. These in turn make use of backends which are 28 | developed separately, and there is no overall community view or guidance as to 29 | the direction these follow. 30 | 31 | Proposed change 32 | --------------- 33 | 34 | We propose a variant on the 35 | `GHC Proposals `_, 36 | namely to use a GitHub repository containing accepted proposals, and to use its 37 | pull request mechanism as a forum to discuss proposed changes. Unlike the GHC 38 | Proposals process, there is no committee acting as a final arbiter of proposal 39 | acceptance, because we recognize that changing the ecosystem requires buy-in 40 | from all the involved parties, it cannot be imposed by a committee. 41 | 42 | Proposal process 43 | ~~~~~~~~~~~~~~~~ 44 | 45 | Each proposal goes through the following stages: 46 | 47 | 1. The process begins with the opening of a pull request to the ecosystem proposals 48 | repository, proposing the merge of a document (derived from a 49 | `provided template `_) 50 | specifying the proposed change. This document is the primary specification 51 | of the feature. 52 | 53 | Due to GitHub's in-place editing feature (the pencil icon visible when viewing 54 | a file on GitHub), proposals can be made quickly without manual forking 55 | or cloning. 56 | 57 | 2. Community members (including representatives of the projects who will 58 | implement the proposed change) will discuss 59 | the proposal. The submitter is responsible for amending the specification to 60 | account for collected comments. It should be expected that the proposal will 61 | change during this process, which may last from days to months. 62 | 63 | 3. When the author feels that all the relevant representatives are on board with 64 | the proposal, and that the proposal would not be improved by further 65 | discussion, they can write a comment indicating that they consider the 66 | proposal accepted. 67 | 68 | 4. One of the maintainers of this GitHub repository will then mark the proposal 69 | as accepted by merging the pull request, and the 70 | document will be preserved in the proposals repository as a permanent 71 | specification for the feature. 72 | 73 | 5. The author will create github issues on the appropriate ecosystem components, 74 | linking to the proposal to provide a place track the progress of the 75 | implementation. 76 | 77 | 6. The author may choose to implement the proposal after acceptance, but she is 78 | under no obligation to do so. (Of course, neither is anyone else. This is why 79 | it is important to get buy-in first.) 80 | 81 | 7. During implementation, it is very likely that the specification will be refined. 82 | The implementor should keep the specification up to date over the course of 83 | the implementation. 84 | 85 | 86 | Criteria for new features 87 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 88 | 89 | When proposing or discussing a change, please take all of the following into 90 | account. 91 | 92 | 1. *The problem*. What exactly is the problem that the feature solves? Is 93 | it an important problem, felt by many users, or is it very specialised? 94 | 95 | 2. *The right solution; generality*. Elegance, economy, and generality are 96 | important. Sometimes a problem has lots of solutions, none of which have that 97 | "aha" feeling of "this is the Right way to solve this". A classic example is 98 | that of records, for which we have had endless proposals (including many from 99 | the GHC authors themselves) none of which felt "right", and none of which 100 | made it into GHC. 101 | 102 | 3. *Fit with the ecosystem*. If we just throw things into the ecosystem 103 | willy-nilly, it will become a large ball of incoherent and inconsistent mud. 104 | Strive to add features that are consistent with the rest of the ecosystem. 105 | 106 | 4. *Specification cost*. Does the benefit of the feature justify the extra 107 | complexity? Does the new feature interact awkwardly with existing features, 108 | or does it enhance them? How easy is it for users to understand the new 109 | feature? 110 | 111 | 5. *Implementation cost*. How complex is the implementation likely to be? Is it 112 | highly localised, or does it require pervasive changes? As an author and 113 | contributor, it may look like you are giving the community free work, but this 114 | viewpoint doesn't align with the reality of a large project with a timescale 115 | in decades. Writing code is cheap; maintaining it is expensive. 116 | 117 | 118 | Drawbacks 119 | --------- 120 | 121 | Of course, group decision-making processes are difficult to manage and tools 122 | will only bring you so far. While the Rust scheme does seem to function more 123 | smoothly than our current system, it is not free of issues (as most recently 124 | discussed by `Aaron Turon 125 | `_). These issues will 126 | likely apply to the process proposed here as well. In particular, 127 | 128 | * GitHub discussions in particular don't scale terribly well; the lack of 129 | hierarchical threading means that long threads can become difficult to follow; 130 | experience suggests that Phabricator seems to be a bit better but long 131 | technical discussions are a challenge for nearly any tool. 132 | 133 | * The ease of commenting may bring a slightly diminished signal-to-noise ratio 134 | in collected feedback, particularly on easily bike-shedded topics. 135 | 136 | 137 | Alternatives 138 | ------------ 139 | 140 | There are a few alternatives which are worth considering, 141 | 142 | * Adopting the process discussed above but replacing GitHub with GitLab. GitLab 143 | has many of the features of GitHub but with the advantage of being open-source 144 | and self-hostable. Unfortunately it would mean introducing yet another tool 145 | into the GHC developer's toolbelt and add yet another piece of infrastructure 146 | to administer. 147 | 148 | * We move to something closer to the Python PEP scheme. Here a committee is 149 | formed for each proposal; the committee is responsible for crafting and 150 | collecting feedback on the proposal. The final acceptance decision is made by 151 | the Benevolant Dictator for Life. Discussion can be carried out on a medium 152 | of the committee's choosing, with a common choice being a specially-created 153 | mailing list. 154 | 155 | * The Rust community has been `considering 156 | `_ breaking their 157 | process up in multiple stages to make their proposal queue more manageable. To 158 | first order these stages are, 159 | 160 | 1. form a consensus around the problem and the need to solve it 161 | 2. propose and refine possible solutions 162 | 3. choose from among the proposed solutions 163 | 164 | The separation of step (1) from the others gives the community a means of 165 | concentrating focus on a set of small problems and encouraging exploration 166 | down multiple solution avenues. The cost of this is that it may frustrate 167 | authors with a slower, more involved process. 168 | 169 | * Something else entirely... 170 | 171 | 172 | Moving closer to the Rust process 173 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 174 | 175 | Also, there are a few facets of the Rust process which the proposed process does 176 | not carry over for a variety of reasons: 177 | 178 | * *Shepherds*. In the Rust process each submitted proposal is assigned a 179 | shepherd. This is a trusted core developer who is charged with keeping the 180 | proposal moving through the process. At the moment GHC arguably lacks the 181 | contributor pool to guarantee this. 182 | 183 | * *Final comment period*. The Rust process defines a portion of the proposal 184 | lifecycle known as the "final comment period". This is a (typically one-week) 185 | period directly before the responsible sub-team makes its decision which is 186 | widely announced to solicit final comments from the community. This period is 187 | omitted from the process described above; instead it is up to the proposal 188 | submitter to ensure that sufficient discussion is solicited. 189 | 190 | Open Questions 191 | -------------- 192 | 193 | There are still questions regarding the desired scope of the process. While we 194 | want to ensure that changes which affect the user-facing aspects of the compiler 195 | are well-considered, we certainly don't want the process to become unduly 196 | burdensome. This is a careful balance which will require care to maintain moving 197 | forward. 198 | 199 | Acknowledgments 200 | --------------- 201 | 202 | Thanks to the GHC Proposals contributors, as well as Herbert Valerio Riedel 203 | and Michael Snoyman for discussions about the concept of the process. 204 | -------------------------------------------------------------------------------- /proposals/0000-template.rst: -------------------------------------------------------------------------------- 1 | .. proposal-number:: Leave blank. This will be filled in when the proposal is 2 | accepted. 3 | 4 | .. highlight:: haskell 5 | 6 | Proposal title 7 | ============== 8 | 9 | Here you should write a short abstract motivating and briefly summarizing the 10 | proposed change. 11 | 12 | Motivation 13 | ---------- 14 | 15 | Here you should describe in greater detail the motivation for the change. This 16 | should include concrete examples of the shortcomings of the current 17 | state of things. 18 | 19 | Proposed Change 20 | --------------- 21 | 22 | Here you should describe in precise terms what the proposal seeks to change. 23 | This should cover several things, 24 | 25 | * define the scope of the change, what does it affect? cabal? stack? a web site? 26 | * define the intended operations of the new change 27 | * discuss how the change addresses the points raised in the Motivation section 28 | * discuss how the proposed approach might interact with existing features 29 | 30 | Note, however, that this section need not describe details of the 31 | implementation of the feature. The proposal is merely supposed to give a 32 | conceptual specification of the new feature and its behavior. 33 | 34 | Drawbacks 35 | --------- 36 | 37 | What are the reasons for *not* adopting the proposed change. These might include 38 | complicating the language grammar, poor interactions with other features, 39 | 40 | Alternatives 41 | ------------ 42 | 43 | Here is where you can describe possible variants to the approach described in 44 | the Proposed Change section. 45 | 46 | Unresolved Questions 47 | -------------------- 48 | 49 | Are there any parts of the design that are still unclear? Hopefully this section 50 | will be empty by the time the proposal is brought up for a final decision. 51 | -------------------------------------------------------------------------------- /rich-diff.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haskell/ecosystem-proposals/12c93a36d3aaa59ce746a7857ecb1a654c17ef68/rich-diff.png --------------------------------------------------------------------------------