├── .gitignore ├── .travis.yml ├── rich-diff.png ├── inline-comment.png ├── shell.nix ├── venv.sh ├── index.rst ├── Makefile ├── proposals ├── 0000-template.md └── 0000-template.rst ├── conf.py └── README.rst /.gitignore: -------------------------------------------------------------------------------- 1 | _build 2 | _venv 3 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: nix 2 | script: nix-shell shell.nix --run "make html" 3 | -------------------------------------------------------------------------------- /rich-diff.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haskell-core/core-libraries-proposals/HEAD/rich-diff.png -------------------------------------------------------------------------------- /inline-comment.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haskell-core/core-libraries-proposals/HEAD/inline-comment.png -------------------------------------------------------------------------------- /shell.nix: -------------------------------------------------------------------------------- 1 | let 2 | np = import {}; 3 | in np.mkShell { buildInputs = [ np.pythonPackages.sphinx ]; } 4 | -------------------------------------------------------------------------------- /venv.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | if [ -z "$SHELL" ]; then 4 | SHELL=/bin/sh 5 | fi 6 | 7 | if [ ! -d _venv ]; then 8 | virtualenv _venv 9 | . _venv/bin/activate 10 | pip install sphinx 11 | exec $SHELL 12 | else 13 | . _venv/bin/activate 14 | exec $SHELL 15 | fi 16 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | All accepted Libraries Proposals 2 | ================================ 3 | 4 | .. toctree:: 5 | :maxdepth: 1 6 | :caption: Contents: 7 | :glob: 8 | 9 | README.rst 10 | proposals/* 11 | 12 | 13 | Indices and tables 14 | ================== 15 | 16 | * :ref:`genindex` 17 | * :ref:`modindex` 18 | * :ref:`search` 19 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | SPHINXPROJ = core-libraries-proposals 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | .PHONY: help 13 | help: 14 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 15 | 16 | # Catch-all target: route all unknown targets to Sphinx using the new 17 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 18 | .PHONY: html 19 | html: 20 | $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /proposals/0000-template.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: Your name 3 | date-accepted: "" 4 | ticket-url: "" 5 | implemented: "" 6 | --- 7 | 8 | This proposal is [discussed at this pull request](https://github.com/haskell-core/core-libraries-proposals/pull/0>). 9 | **After creating the pull request, edit this file again, update the number in 10 | the link, and delete this bold sentence.** 11 | 12 | # Proposal title 13 | 14 | Here you should write a short abstract motivating and briefly summarizing the 15 | proposed change. 16 | 17 | 18 | ## Motivation 19 | 20 | Give a strong reason for why the community needs this change. Describe the use 21 | case as clearly as possible and give an example. Explain how the status quo is 22 | insufficient or not ideal. 23 | 24 | A good Motivation section is often driven by examples and real-world scenarios. 25 | 26 | 27 | ## Proposed Change Specification 28 | 29 | Specify the change in precise, comprehensive yet concise language. Avoid words 30 | like "should" or "could". Strive for a complete definition. Your specification 31 | may include, 32 | 33 | * BNF grammar and semantics of any new syntactic constructs 34 | * the types and semantics of any new library interfaces 35 | * how the proposed change interacts with existing language or compiler 36 | features, in case that is otherwise ambiguous 37 | 38 | Note, however, that this section need not describe details of the 39 | implementation of the feature or examples. The proposal is merely supposed to 40 | give a conceptual specification of the new feature and its behavior. 41 | 42 | ## Examples 43 | 44 | This section illustrates the specification through the use of examples of the 45 | language change proposed. It is best to exemplify each point made in the 46 | specification, though perhaps one example can cover several points. Contrived 47 | examples are OK here. If the Motivation section describes something that is 48 | hard to do without this proposal, this is a good place to show how easy that 49 | thing is to do with the proposal. 50 | 51 | ## Effect and Interactions 52 | 53 | Detail how the proposed change addresses the original problem raised in the 54 | motivation. 55 | 56 | Discuss possibly contentious interactions with existing language or compiler 57 | features. 58 | 59 | 60 | ## Costs and Drawbacks 61 | 62 | Give an estimate on development and maintenance costs. List how this effects 63 | learnability of the language for novice users. Define and list any remaining 64 | drawbacks that cannot be resolved. 65 | 66 | 67 | ## Alternatives 68 | 69 | List existing alternatives to your proposed change as they currently exist and 70 | discuss why they are insufficient. 71 | 72 | 73 | ## Unresolved Questions 74 | 75 | Explicitly list any remaining issues that remain in the conceptual design and 76 | specification. Be upfront and trust that the community will help. Please do 77 | not list *implementation* issues. 78 | 79 | Hopefully this section will be empty by the time the proposal is brought to 80 | the steering committee. 81 | 82 | 83 | ## Implementation Plan 84 | 85 | (Optional) If accepted who will implement the change? Which other resources 86 | and prerequisites are required for implementation? 87 | 88 | ## Endorsements 89 | 90 | (Optional) This section provides an opportunty for any third parties to express their 91 | support for the proposal, and to say why they would like to see it adopted. 92 | It is not mandatory for have any endorsements at all, but the more substantial 93 | the proposal is, the more desirable it is to offer evidence that there is 94 | significant demand from the community. This section is one way to provide 95 | such evidence. 96 | 97 | -------------------------------------------------------------------------------- /proposals/0000-template.rst: -------------------------------------------------------------------------------- 1 | Notes on reStructuredText - delete this section before submitting 2 | ================================================================== 3 | 4 | The proposals are submitted in reStructuredText format. To get inline code, enclose text in double backticks, ``like this``. To get block code, use a double colon and indent by at least one space 5 | 6 | :: 7 | 8 | like this 9 | and 10 | 11 | this too 12 | 13 | To get hyperlinks, use backticks, angle brackets, and an underscore `like this `_. 14 | 15 | 16 | Proposal title 17 | ============== 18 | 19 | .. author:: Your name 20 | .. date-accepted:: Leave blank. This will be filled in when the proposal is accepted. 21 | .. ticket-url:: Leave blank. This will eventually be filled with the 22 | ticket URL which will track the progress of the 23 | implementation of the feature. 24 | .. implemented:: Leave blank. This will be filled in with the first library version which 25 | implements the described feature. 26 | .. highlight:: haskell 27 | .. header:: This proposal is `discussed at this pull request `_. 28 | **After creating the pull request, edit this file again, update the 29 | number in the link, and delete this bold sentence.** 30 | .. contents:: 31 | 32 | Here you should write a short abstract motivating and briefly summarizing the proposed change. 33 | 34 | 35 | Motivation 36 | ---------- 37 | Give a strong reason for why the community needs this change. Describe the use 38 | case as clearly as possible and give an example. Explain how the status quo is 39 | insufficient or not ideal. 40 | 41 | A good Motivation section is often driven by examples and real-world scenarios. 42 | 43 | 44 | Proposed Change Specification 45 | ----------------------------- 46 | Specify the change in precise, comprehensive yet concise language. Avoid words 47 | like "should" or "could". Strive for a complete definition. Your specification 48 | may include, 49 | 50 | * BNF grammar and semantics of any new syntactic constructs 51 | * the types and semantics of any new library interfaces 52 | * how the proposed change interacts with existing language or compiler 53 | features, in case that is otherwise ambiguous 54 | 55 | Note, however, that this section need not describe details of the 56 | implementation of the feature or examples. The proposal is merely supposed to 57 | give a conceptual specification of the new feature and its behavior. 58 | 59 | Examples 60 | -------- 61 | This section illustrates the specification through the use of examples of the 62 | language change proposed. It is best to exemplify each point made in the 63 | specification, though perhaps one example can cover several points. Contrived 64 | examples are OK here. If the Motivation section describes something that is 65 | hard to do without this proposal, this is a good place to show how easy that 66 | thing is to do with the proposal. 67 | 68 | Effect and Interactions 69 | ----------------------- 70 | Detail how the proposed change addresses the original problem raised in the 71 | motivation. 72 | 73 | Discuss possibly contentious interactions with existing language or compiler 74 | features. 75 | 76 | 77 | Costs and Drawbacks 78 | ------------------- 79 | Give an estimate on development and maintenance costs. List how this effects 80 | learnability of the language for novice users. Define and list any remaining 81 | drawbacks that cannot be resolved. 82 | 83 | 84 | Alternatives 85 | ------------ 86 | List existing alternatives to your proposed change as they currently exist and 87 | discuss why they are insufficient. 88 | 89 | 90 | Unresolved Questions 91 | -------------------- 92 | Explicitly list any remaining issues that remain in the conceptual design and 93 | specification. Be upfront and trust that the community will help. Please do 94 | not list *implementation* issues. 95 | 96 | Hopefully this section will be empty by the time the proposal is brought to 97 | the steering committee. 98 | 99 | 100 | Implementation Plan 101 | ------------------- 102 | (Optional) If accepted who will implement the change? Which other resources 103 | and prerequisites are required for implementation? 104 | 105 | Endorsements 106 | ------------- 107 | (Optional) This section provides an opportunty for any third parties to express their 108 | support for the proposal, and to say why they would like to see it adopted. 109 | It is not mandatory for have any endorsements at all, but the more substantial 110 | the proposal is, the more desirable it is to offer evidence that there is 111 | significant demand from the community. This section is one way to provide 112 | such evidence. 113 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # Configuration file for the Sphinx documentation builder. 4 | # 5 | # This file does only contain a selection of the most common options. For a 6 | # full list see the documentation: 7 | # http://www.sphinx-doc.org/en/master/config 8 | 9 | # -- Path setup -------------------------------------------------------------- 10 | 11 | # If extensions (or modules to document with autodoc) are in another directory, 12 | # add these directories to sys.path here. If the directory is relative to the 13 | # documentation root, use os.path.abspath to make it absolute, like shown here. 14 | # 15 | # import os 16 | # import sys 17 | # sys.path.insert(0, os.path.abspath('.')) 18 | 19 | 20 | # -- Project information ----------------------------------------------------- 21 | 22 | project = u'core-libraries-proposals' 23 | copyright = u'2020, The Haskell Core Libraries Committee' 24 | author = u'The Haskell Core Libraries Committee' 25 | 26 | # The short X.Y version 27 | version = u'' 28 | # The full version, including alpha/beta/rc tags 29 | release = u'' 30 | 31 | 32 | # -- General configuration --------------------------------------------------- 33 | 34 | # If your documentation needs a minimal Sphinx version, state it here. 35 | # 36 | # needs_sphinx = '1.0' 37 | 38 | # Add any Sphinx extension module names here, as strings. They can be 39 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 40 | # ones. 41 | extensions = [ 42 | ] 43 | 44 | # Add any paths that contain templates here, relative to this directory. 45 | templates_path = ['_templates'] 46 | 47 | # The suffix(es) of source filenames. 48 | # You can specify multiple suffix as a list of string: 49 | # 50 | # source_suffix = ['.rst', '.md'] 51 | source_suffix = '.rst' 52 | 53 | # The master toctree document. 54 | master_doc = 'index' 55 | 56 | # The language for content autogenerated by Sphinx. Refer to documentation 57 | # for a list of supported languages. 58 | # 59 | # This is also used if you do content translation via gettext catalogs. 60 | # Usually you set "language" from the command line for these cases. 61 | language = None 62 | 63 | # List of patterns, relative to source directory, that match files and 64 | # directories to ignore when looking for source files. 65 | # This pattern also affects html_static_path and html_extra_path . 66 | exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', "proposals/0000-template.rst"] 67 | 68 | # The name of the Pygments (syntax highlighting) style to use. 69 | pygments_style = 'sphinx' 70 | 71 | 72 | # -- Options for HTML output ------------------------------------------------- 73 | 74 | # The theme to use for HTML and HTML Help pages. See the documentation for 75 | # a list of builtin themes. 76 | # 77 | html_theme = 'haiku' 78 | 79 | # Theme options are theme-specific and customize the look and feel of a theme 80 | # further. For a list of options available for each theme, see the 81 | # documentation. 82 | # 83 | # html_theme_options = {} 84 | 85 | # Add any paths that contain custom static files (such as style sheets) here, 86 | # relative to this directory. They are copied after the builtin static files, 87 | # so a file named "default.css" will overwrite the builtin "default.css". 88 | html_static_path = ['_static'] 89 | 90 | # Custom sidebar templates, must be a dictionary that maps document names 91 | # to template names. 92 | # 93 | # The default sidebars (for documents that don't match any pattern) are 94 | # defined by theme itself. Builtin themes are using these templates by 95 | # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', 96 | # 'searchbox.html']``. 97 | # 98 | # html_sidebars = {} 99 | 100 | 101 | # -- Options for HTMLHelp output --------------------------------------------- 102 | 103 | # Output file base name for HTML help builder. 104 | htmlhelp_basename = 'core-libraries-proposalsdoc' 105 | 106 | 107 | # -- Options for LaTeX output ------------------------------------------------ 108 | 109 | latex_elements = { 110 | # The paper size ('letterpaper' or 'a4paper'). 111 | # 112 | # 'papersize': 'letterpaper', 113 | 114 | # The font size ('10pt', '11pt' or '12pt'). 115 | # 116 | # 'pointsize': '10pt', 117 | 118 | # Additional stuff for the LaTeX preamble. 119 | # 120 | # 'preamble': '', 121 | 122 | # Latex figure (float) alignment 123 | # 124 | # 'figure_align': 'htbp', 125 | } 126 | 127 | # Grouping the document tree into LaTeX files. List of tuples 128 | # (source start file, target name, title, 129 | # author, documentclass [howto, manual, or own class]). 130 | latex_documents = [ 131 | (master_doc, 'core-libraries-proposals.tex', u'Core Libraries Proposals', 132 | u'CLC', 'manual'), 133 | ] 134 | 135 | 136 | # -- Options for manual page output ------------------------------------------ 137 | 138 | # One entry per manual page. List of tuples 139 | # (source start file, name, description, authors, manual section). 140 | man_pages = [ 141 | (master_doc, 'core-libraries-proposals', u'Core Libraries Proposals', 142 | [author], 1) 143 | ] 144 | 145 | 146 | # -- Options for Texinfo output ---------------------------------------------- 147 | 148 | # Grouping the document tree into Texinfo files. List of tuples 149 | # (source start file, target name, title, author, 150 | # dir menu entry, description, category) 151 | texinfo_documents = [ 152 | (master_doc, 'core-libraries-proposals', u'Core Libraries Proposals', 153 | author, 'core-libraries-proposals', 'One line description of project.', 154 | 'Miscellaneous'), 155 | ] 156 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | Core Libraries Proposals 2 | ======================== 3 | 4 | This repository contains specifications for proposed changes to the `Haskell Core Libraries `_. 5 | The purpose of the Libraries proposal process and of the CLC, is to ensure the healthy development of Haskell's core libraries. 6 | 7 | * `≡ List of proposals under discussion `_ 8 | * `≡ List of proposals waiting for shepherd recommendation `_ 9 | * `≡ List of proposals waiting for committee decision `_ 10 | * `≡ List of accepted proposals `_ 11 | * `≡ List of rejected proposals `_ 12 | * `≡ List of implemented proposals `_ 13 | * `≡ List of all proposals `_ 14 | 15 | What is a core library? 16 | ----------------------- 17 | 18 | A core library is simply one which is maintained by the Core Libraries Committee, or CLC. For more details on how libraries are determined to be core, and which libraries are currently considered core, see the `CLC document `_. We encourage you to read that document to better understand the relationship between core libraries and the CLC, as it will make understanding the scope of the Libraries Proposal process simpler. 19 | 20 | What is a proposal? 21 | ------------------- 22 | 23 | A Libraries Proposal is a document describing a proposed change to the API of a core library. These do not include things like 24 | 25 | * Bugfixes 26 | * Minor changes 27 | 28 | These do include 29 | 30 | * Breaking changes to the API of a library 31 | * "Controversial" changes, as defined by the `Controversial Decisions `_ section of the CLC Document 32 | 33 | Changes to libraries not deemed core are not automatically within the scope of 34 | the committee, and can be contributed following the workflow set forth by the respective maintainers of those libraries. 35 | 36 | Should a maintainer(s) of a core library deem a change significant or controversial enough to warrant a proposal, they may, at their discretion, involve the CLC and ask the contributor(s) to write a formal proposal. 37 | 38 | The life cycle of a proposal 39 | ----------------------------------- 40 | 41 | This section outlines what stages a proposal may go through. The stage is identified by a GitHub label, which is identified in the following list. 42 | 43 | 1. (No label.) The author drafts a proposal. 44 | 45 | `What is a proposal? <#what-is-a-proposal>`_ • `What should a proposal look like? <#what-should-a-proposal-look-like>`_ 46 | 47 | 2. (No label.) The author submits the proposal to the wider Haskell community for discussion, as a pull request against this repository. 48 | 49 | `How to submit a proposal <#how-to-start-a-new-proposal>`_ 50 | 51 | 3. (No label.) The wider community discusses the proposal in the comment section of the pull 52 | request, while the author refines the proposal. This phase lasts as long as necessary. 53 | 54 | `Discussion goals <#discussion-goals>`_ • 55 | `How to comment on a proposal <#how-to-comment-on-a-proposal>`_ • 56 | `≡ List of proposals under discussion `_ 57 | 58 | 4. Label: `Pending shepherd recommendation `_. Eventually *the proposal author* brings the proposal before the committee for review. 59 | 60 | `How to bring a proposal before the committee <#how-to-bring-a-proposal-before-the-committee>`_ • 61 | `Who is the committee? <#who-is-the-committee>`_ • 62 | `≡ List of proposals waiting for shepherd `_ • 63 | 64 | 5. Label: `Pending committee review `_. One committee member steps up as a shepherd, and generates consensus within the committee within four or five weeks. 65 | 66 | `Committee process <#committee-process>`_ • 67 | `Review criteria <#review-criteria>`_ • 68 | `≡ List of proposals under review `_ 69 | 70 | 6. Eventually, the committee rejects a proposal (label: Rejected), or passes it back to the 71 | author for review (label: `Needs revision `_), or accepts it (label: `Accepted `_). 72 | 73 | Acceptance of the proposal implies that the implementation will be accepted 74 | into the library, provided it is well-engineered, well-documented, and does not 75 | complicate the code-base too much. 76 | 77 | `≡ List of accepted proposals `_ • 78 | `≡ List of proposals being revised `_ • 79 | `≡ List of rejected proposals `_ 80 | 81 | 7. Label: `Dormant `_. If a proposal sees no activity for along time, it is marked as “dormant”, 82 | and eventually closed. 83 | 84 | `What is a dormant proposal? <#what-is-a-dormant-proposal>`_ • 85 | `≡ List of dormant proposals `_ 86 | 87 | 88 | 8. Label: `Implemented `_. Once a proposal is accepted, it still has to be implemented. The author 89 | may do that, or someone else. We mark the proposal as “implemented” once it 90 | hits the library’s ``master`` branch (and we are happy to be nudged to do so by 91 | email or GitHub issue). 92 | 93 | `≡ List of implemented proposals `_ 94 | 95 | Do not hesitate to `contact <#questions>`_ us if you have questions. 96 | 97 | How to start a new proposal 98 | --------------------------- 99 | 100 | Proposals are written in either `ReStructuredText `_ or `Markdown `_. The proposal process itself has no preference, so proposal authors are free to write in whichever they please. 101 | 102 | Proposals should follow the structure given in the `ReStructuredText template `_, or the `Markdown template `_. (The two are identical except for format.) 103 | 104 | See the section `Review criteria <#review-criteria>`_ below for more information about what makes a strong proposal, and how it will be reviewed. 105 | 106 | To start a proposal, create a pull request that adds your proposal as ``proposals/0000-proposal-name.rst`` or ``proposals/0000-proposal-name.md``. Use the corresponding ``proposals/0000-template`` file as a template. 107 | 108 | If you are unfamiliar with git and github, you can use the GitHub web interface to perform these steps: 109 | 110 | 1. Load the proposal template using `this link (ReStructuredText)`__ or `this link (Markdown)`__. 111 | 2. Change the filename and edit the proposal. 112 | 3. Press “Commit new file” 113 | 114 | __ https://github.com/haskell-core/core-libraries-proposals/new/master?filename=proposals/new-proposal.rst;message=Start%20new%20proposal;value=Notes%20on%20reStructuredText%20-%20delete%20this%20section%20before%20submitting%0A%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%0A%0AThe%20proposals%20are%20submitted%20in%20reStructuredText%20format.%20%20To%20get%20inline%20code%2C%20enclose%20text%20in%20double%20backticks%2C%20%60%60like%20this%60%60.%20%20To%20get%20block%20code%2C%20use%20a%20double%20colon%20and%20indent%20by%20at%20least%20one%20space%0A%0A%3A%3A%0A%0A%20like%20this%0A%20and%0A%0A%20this%20too%0A%0ATo%20get%20hyperlinks%2C%20use%20backticks%2C%20angle%20brackets%2C%20and%20an%20underscore%20%60like%20this%20%3Chttp%3A//www.haskell.org/%3E%60_.%0A%0A%0AProposal%20title%0A%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%0A%0A..%20author%3A%3A%20Your%20name%0A..%20date-accepted%3A%3A%20Leave%20blank.%20This%20will%20be%20filled%20in%20when%20the%20proposal%20is%20accepted.%0A..%20proposal-number%3A%3A%20Leave%20blank.%20This%20will%20be%20filled%20in%20when%20the%20proposal%20is%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20accepted.%0A..%20ticket-url%3A%3A%20Leave%20blank.%20This%20will%20eventually%20be%20filled%20with%20the%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20ticket%20URL%20which%20will%20track%20the%20progress%20of%20the%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20implementation%20of%20the%20feature.%0A..%20implemented%3A%3A%20Leave%20blank.%20This%20will%20be%20filled%20in%20with%20the%20first%20GHC%20version%20which%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20implements%20the%20described%20feature.%0A..%20highlight%3A%3A%20haskell%0A..%20header%3A%3A%20This%20proposal%20is%20%60discussed%20at%20this%20pull%20request%20%3Chttps%3A//github.com/haskell-core/core-libraries-proposals/pull/0%3E%60_.%0A%20%20%20%20%20%20%20%20%20%20%20%20%2A%2AAfter%20creating%20the%20pull%20request%2C%20edit%20this%20file%20again%2C%20update%20the%0A%20%20%20%20%20%20%20%20%20%20%20%20number%20in%20the%20link%2C%20and%20delete%20this%20bold%20sentence.%2A%2A%0A..%20sectnum%3A%3A%0A..%20contents%3A%3A%0A%0AHere%20you%20should%20write%20a%20short%20abstract%20motivating%20and%20briefly%20summarizing%20the%20proposed%20change.%0A%0A%0AMotivation%0A----------%0AGive%20a%20strong%20reason%20for%20why%20the%20community%20needs%20this%20change.%20Describe%20the%20use%0Acase%20as%20clearly%20as%20possible%20and%20give%20an%20example.%20Explain%20how%20the%20status%20quo%20is%0Ainsufficient%20or%20not%20ideal.%0A%0AA%20good%20Motivation%20section%20is%20often%20driven%20by%20examples%20and%20real-world%20scenarios.%0A%0A%0AProposed%20Change%20Specification%0A-----------------------------%0ASpecify%20the%20change%20in%20precise%2C%20comprehensive%20yet%20concise%20language.%20Avoid%20words%0Alike%20%22should%22%20or%20%22could%22.%20Strive%20for%20a%20complete%20definition.%20Your%20specification%0Amay%20include%2C%0A%0A%2A%20grammar%20and%20semantics%20of%20any%20new%20syntactic%20constructs%0A%2A%20the%20types%20and%20semantics%20of%20any%20new%20library%20interfaces%0A%2A%20how%20the%20proposed%20change%20interacts%20with%20existing%20language%20or%20compiler%0A%20%20features%2C%20in%20case%20that%20is%20otherwise%20ambiguous%0A%0ANote%2C%20however%2C%20that%20this%20section%20need%20not%20describe%20details%20of%20the%0Aimplementation%20of%20the%20feature%20or%20examples.%20The%20proposal%20is%20merely%20supposed%20to%0Agive%20a%20conceptual%20specification%20of%20the%20new%20feature%20and%20its%20behavior.%0A%0AExamples%0A--------%0AThis%20section%20illustrates%20the%20specification%20through%20the%20use%20of%20examples%20of%20the%0Alanguage%20change%20proposed.%20It%20is%20best%20to%20exemplify%20each%20point%20made%20in%20the%0Aspecification%2C%20though%20perhaps%20one%20example%20can%20cover%20several%20points.%20Contrived%0Aexamples%20are%20OK%20here.%20If%20the%20Motivation%20section%20describes%20something%20that%20is%0Ahard%20to%20do%20without%20this%20proposal%2C%20this%20is%20a%20good%20place%20to%20show%20how%20easy%20that%0Athing%20is%20to%20do%20with%20the%20proposal.%0A%0AEffect%20and%20Interactions%0A-----------------------%0ADetail%20how%20the%20proposed%20change%20addresses%20the%20original%20problem%20raised%20in%20the%0Amotivation.%0A%0ADiscuss%20possibly%20contentious%20interactions%20with%20existing%20language%20or%20compiler%0Afeatures.%0A%0A%0ACosts%20and%20Drawbacks%0A-------------------%0AGive%20an%20estimate%20on%20development%20and%20maintenance%20costs.%20List%20how%20this%20effects%0Alearnability%20of%20the%20language%20for%20novice%20users.%20Define%20and%20list%20any%20remaining%0Adrawbacks%20that%20cannot%20be%20resolved.%0A%0A%0AAlternatives%0A------------%0AList%20existing%20alternatives%20to%20your%20proposed%20change%20as%20they%20currently%20exist%20and%0Adiscuss%20why%20they%20are%20insufficient.%0A%0A%0AUnresolved%20Questions%0A--------------------%0AExplicitly%20list%20any%20remaining%20issues%20that%20remain%20in%20the%20conceptual%20design%20and%0Aspecification.%20Be%20upfront%20and%20trust%20that%20the%20community%20will%20help.%20Please%20do%0Anot%20list%20%2Aimplementation%2A%20issues.%0A%0AHopefully%20this%20section%20will%20be%20empty%20by%20the%20time%20the%20proposal%20is%20brought%20to%0Athe%20steering%20committee.%0A%0A%0AImplementation%20Plan%0A-------------------%0A%28Optional%29%20If%20accepted%20who%20will%20implement%20the%20change%3F%20Which%20other%20resources%0Aand%20prerequisites%20are%20required%20for%20implementation%3F%0A 115 | 116 | .. link generated with 117 | python -c "import urllib;print 'https://github.com/haskell-core/core-libraries-proposals/new/master?filename=proposals/new-proposal.rst;message=%s;value=%s' % (urllib.quote('Start new proposal'), urllib.quote(file('proposals/0000-template.rst').read()))" 118 | 119 | __ https://github.com/haskell-core/core-libraries-proposals/new/master?filename=proposals/new-proposal.md;message=Start%20new%20proposal;value=---%0Aauthor%3A%20Your%20name%0Adate-accepted%3A%20%22%22%0Aproposal-number%3A%20%22%22%0Aticket-url%3A%20%22%22%0Aimplemented%3A%20%22%22%0A---%0A%0AThis%20proposal%20is%20%5Bdiscussed%20at%20this%20pull%20request%5D%28https%3A//github.com/haskell-core/core-libraries-proposals/pull/0%3E%29.%0A%2A%2AAfter%20creating%20the%20pull%20request%2C%20edit%20this%20file%20again%2C%20update%20the%20number%20in%0Athe%20link%2C%20and%20delete%20this%20bold%20sentence.%2A%2A%0A%0A%23%20Proposal%20title%0A%0AHere%20you%20should%20write%20a%20short%20abstract%20motivating%20and%20briefly%20summarizing%20the%0Aproposed%20change.%0A%0A%0A%23%23%20Motivation%0A%0AGive%20a%20strong%20reason%20for%20why%20the%20community%20needs%20this%20change.%20Describe%20the%20use%0Acase%20as%20clearly%20as%20possible%20and%20give%20an%20example.%20Explain%20how%20the%20status%20quo%20is%0Ainsufficient%20or%20not%20ideal.%0A%0AA%20good%20Motivation%20section%20is%20often%20driven%20by%20examples%20and%20real-world%20scenarios.%0A%0A%0A%23%23%20Proposed%20Change%20Specification%0A%0ASpecify%20the%20change%20in%20precise%2C%20comprehensive%20yet%20concise%20language.%20Avoid%20words%0Alike%20%22should%22%20or%20%22could%22.%20Strive%20for%20a%20complete%20definition.%20Your%20specification%0Amay%20include%2C%0A%0A%2A%20grammar%20and%20semantics%20of%20any%20new%20syntactic%20constructs%0A%2A%20the%20types%20and%20semantics%20of%20any%20new%20library%20interfaces%0A%2A%20how%20the%20proposed%20change%20interacts%20with%20existing%20language%20or%20compiler%0A%20%20features%2C%20in%20case%20that%20is%20otherwise%20ambiguous%0A%0ANote%2C%20however%2C%20that%20this%20section%20need%20not%20describe%20details%20of%20the%0Aimplementation%20of%20the%20feature%20or%20examples.%20The%20proposal%20is%20merely%20supposed%20to%0Agive%20a%20conceptual%20specification%20of%20the%20new%20feature%20and%20its%20behavior.%0A%0A%23%23%20Examples%0A%0AThis%20section%20illustrates%20the%20specification%20through%20the%20use%20of%20examples%20of%20the%0Alanguage%20change%20proposed.%20It%20is%20best%20to%20exemplify%20each%20point%20made%20in%20the%0Aspecification%2C%20though%20perhaps%20one%20example%20can%20cover%20several%20points.%20Contrived%0Aexamples%20are%20OK%20here.%20If%20the%20Motivation%20section%20describes%20something%20that%20is%0Ahard%20to%20do%20without%20this%20proposal%2C%20this%20is%20a%20good%20place%20to%20show%20how%20easy%20that%0Athing%20is%20to%20do%20with%20the%20proposal.%0A%0A%23%23%20Effect%20and%20Interactions%0A%0ADetail%20how%20the%20proposed%20change%20addresses%20the%20original%20problem%20raised%20in%20the%0Amotivation.%0A%0ADiscuss%20possibly%20contentious%20interactions%20with%20existing%20language%20or%20compiler%0Afeatures.%0A%0A%0A%23%23%20Costs%20and%20Drawbacks%0A%0AGive%20an%20estimate%20on%20development%20and%20maintenance%20costs.%20List%20how%20this%20effects%0Alearnability%20of%20the%20language%20for%20novice%20users.%20Define%20and%20list%20any%20remaining%0Adrawbacks%20that%20cannot%20be%20resolved.%0A%0A%0A%23%23%20Alternatives%0A%0AList%20existing%20alternatives%20to%20your%20proposed%20change%20as%20they%20currently%20exist%20and%0Adiscuss%20why%20they%20are%20insufficient.%0A%0A%0A%23%23%20Unresolved%20Questions%0A%0AExplicitly%20list%20any%20remaining%20issues%20that%20remain%20in%20the%20conceptual%20design%20and%0Aspecification.%20Be%20upfront%20and%20trust%20that%20the%20community%20will%20help.%20Please%20do%0Anot%20list%20%2Aimplementation%2A%20issues.%0A%0AHopefully%20this%20section%20will%20be%20empty%20by%20the%20time%20the%20proposal%20is%20brought%20to%0Athe%20steering%20committee.%0A%0A%0A%23%23%20Implementation%20Plan%0A%0A%28Optional%29%20If%20accepted%20who%20will%20implement%20the%20change%3F%20Which%20other%20resources%0Aand%20prerequisites%20are%20required%20for%20implementation%3F%0A%0A 120 | 121 | .. link generated with 122 | python -c "import urllib;print 'https://github.com/haskell-core/core-libraries-proposals/new/master?filename=proposals/new-proposal.md;message=%s;value=%s' % (urllib.quote('Start new proposal'), urllib.quote(file('proposals/0000-template.md').read()))" 123 | 124 | The pull request summary should include a brief description of your 125 | proposal, along with a link to the rendered view of proposal document 126 | in your branch. For instance, 127 | 128 | .. code-block:: md 129 | 130 | This is a proposal aiming to unify `Nat` and `Natural`. 131 | 132 | [Rendered](https://github.com/chessai/core-libraries-proposals/blob/typeable/proposals/0000-type-indexed-typeable.rst) 133 | 134 | How to amend an accepted proposal 135 | --------------------------------- 136 | 137 | Some proposals amend an existing proposal. Such an amendment: 138 | 139 | * Makes a significant (i.e. not just editorial or typographical) change, and hence warrants approval by the committee 140 | * Is too small, or too closely tied to the existing proposal, to make sense as a new standalone proposal. 141 | 142 | Often, this happens 143 | after a proposal is accepted, but before or while it is implemented. 144 | In these cases, a PR that *changes* the accepted proposal can be opened. It goes through 145 | the same process as an original proposal. 146 | 147 | Discussion goals 148 | ---------------- 149 | 150 | Members of the Haskell community are warmly invited to offer feedback on 151 | proposals. Feedback ensures that a variety of perspectives are heard, that 152 | alternative designs are considered, and that all of the pros and cons of a 153 | design are uncovered. Feedback by the maintainers of the library is *highly* 154 | encouraged. We particularly encourage the following types of feedback, 155 | 156 | - Completeness: Is the proposal missing a case? 157 | - Soundness: Is the specification sound or does it include mistakes? 158 | - Alternatives: Are all reasonable alternatives listed and discussed. Are the pros and cons argued convincingly? 159 | - Costs: Are the costs for implementation believable and understandable? 160 | - Other questions: Ask critical questions that need to be resolved. 161 | - Motivation: Is the motivation reasonable? 162 | 163 | How to comment on a proposal 164 | ----------------------------- 165 | 166 | To comment on a proposal you need to be viewing the proposal's diff in "source 167 | diff" view. To switch to this view use the buttons on the top-right corner of 168 | the *Files Changed* tab. 169 | 170 | .. figure:: rich-diff.png 171 | :alt: The view selector buttons. 172 | :align: right 173 | 174 | Use the view selector buttons on the top right corner of the "Files 175 | Changed" tab to change between "source diff" and "rich diff" views. 176 | 177 | Feedback on a open pull requests can be offered using both GitHub's in-line and 178 | pull request commenting features. Inline comments can be added by hovering over 179 | a line of the diff. 180 | 181 | .. figure:: inline-comment.png 182 | :alt: The ``+`` button appears while hovering over line in the source diff view. 183 | :align: right 184 | 185 | Hover over a line in the source diff view of a pull request and 186 | click on the ``+`` to leave an inline comment 187 | 188 | For the maintenance of general sanity, try to avoid leaving "me too" comments. 189 | If you would like to register your approval or disapproval of a particular 190 | comment or proposal, feel free to use GitHub's "Reactions" 191 | `feature `_. 192 | 193 | How to bring a proposal before the committee 194 | --------------------------------------------- 195 | 196 | When the discussion has ebbed down and the author thinks the proposal is ready, they 197 | 198 | 1. Review the discussion thread and ensure that the proposal text accounts for 199 | all salient points. *Remember, the proposal must stand by itself, and be understandable 200 | without reading the discussion thread.* 201 | 2. Add a comment to the a pull request, briefly summarizing the major points raised 202 | during the discussion period and stating your belief that the proposal is 203 | ready for review. In this comment, tag the committee secretary (currently 204 | ``@chessai``). 205 | 206 | `The secretary <#who-is-the-committee>`_ will then label the pull request with 207 | ``Pending shepherd recommendation`` and start the `committee process 208 | <#committee-process>`_. (If this does not happen within a day or two, please 209 | ping the secretary or the committee.) 210 | 211 | What is a dormant proposal? 212 | -------------------------- 213 | 214 | In order to keep better track of actively discussed proposals, proposals that 215 | see no activity for an extended period of time (a month or two) might be marked 216 | as “``dormant``”. At any time the proposer, or someone else can revive the 217 | proposal by picking up the discussion (and possibly asking `the secretary 218 | <#who-is-the-committee>`_ to remove the ``dormant`` tag). 219 | 220 | You can see the `list of dormant proposals `_. 221 | 222 | Who is the committee? 223 | -------------------- 224 | You can reach the committee by email at core-libraries-committee@haskell.org. 225 | 226 | The current members, including their GitHub handle, when they joined and their role, are listed at: 227 | 228 | ====================== ==================================================== ======= ================ 229 | chessai `@chessai `_ 2020/09 chair, secretary 230 | Cale Gibbard `@cgibbard `_ 2020/09 231 | Edward Kmett `@ekmett `_ 2020/09 232 | Andrew Thaddeus Martin `@andrewthad `_ 2020/09 233 | Eric Mertens `@glguy `_ 2020/09 234 | Neil Mitchell `@ndmitchell `_ 2020/09 235 | Emily Pillmore `@emilypi `_ 2020/09 236 | Herbert Valerio Riedel `@hvr `_ 2020/09 237 | George Wilson `@gwils `_ 2020/09 238 | ====================== ==================================================== ======= ================ 239 | 240 | Committee process 241 | ----------------- 242 | 243 | The committee process starts once the secretary has been notified that a 244 | proposal is ready for decision. 245 | 246 | The steps below have timescales attached, so that everyone shares 247 | the same expectations. But they are only reasonable expectations. 248 | The committee consists of volunteers with day jobs, who are reviewing 249 | proposals in their spare time. If they do not meet the timescales 250 | indicated below (e.g., they might be on holiday), a reasonable response 251 | is a polite ping/enquiry. 252 | 253 | - The secretary nominates a member of the committee, the *shepherd*, to oversee 254 | the discussion. The secretary 255 | 256 | * labels the proposal as ``Pending shepherd recommendation``, 257 | * assigns the proposal to the shepherd, 258 | * drops a short mail on the mailing list, informing the committee about the 259 | status change. 260 | 261 | - Based on the proposal text (but not the GitHub commentary), the shepherd 262 | decides whether the proposal ought to be accepted or rejected or returned for 263 | revision. The shepherd should do this within two weeks. 264 | 265 | - If the shepherd thinks the proposal ought to be rejected, they post their 266 | justifications on the GitHub thread, and invite the authors to respond with 267 | a rebuttal and/or refine the proposal. This continues until either 268 | 269 | * the shepherd changes their mind and supports the proposal now, 270 | * the authors withdraw their proposal, 271 | * the authors indicate that they will revise the proposal to address the shepherds 272 | point. The shepherd will label the pull request as 273 | `Needs Revision `_. 274 | * the authors and the shepherd fully understand each other’s differing 275 | positions, even if they disagree on the conclusion. 276 | 277 | - Now the shepherd proposes to accept or reject the proposal. To do so, they 278 | 279 | * post their recommendation, with a rationale, on the GitHub discussion thread, 280 | * label the pull request as ``Pending committee review``, 281 | * re-title the proposal pull request, appending ``(under review)`` at the end. (This enables easy email filtering.) 282 | * drop a short mail to the mailing list informing the committee that 283 | discussion has started. 284 | 285 | - Discussion among the committee ensues, in two places 286 | 287 | * *Technical discussion* takes place on the discussion thread, where others may 288 | continue to contribute. 289 | 290 | * *Evaluative discussion*, about whether to accept, reject, or return the 291 | proposal for revision, takes place on the committee's email list, 292 | which others can read but not post to. 293 | 294 | It is expected that every committee member express an opinion about every proposal under review. 295 | The most minimal way to do this is to "thumbs-up" the shepherd's recommendation on GitHub. 296 | 297 | Ideally, the committee reaches consensus, as determined by the secretary or 298 | the shepherd. If consensus is elusive, then we vote, with the chair 299 | retaining veto power. 300 | 301 | This phase should conclude within a month. 302 | 303 | - For acceptance, a proposal must have at least *some* enthusiastic support 304 | from member(s) of the committee. The committee, fallible though its members may be, 305 | is the guardian of the core libraries. If all of them are lukewarm about a change, 306 | there is a presumption that it should be rejected, or at least "parked". 307 | (See "evidence of utility" above, under "What a proposal should look like".) 308 | 309 | - A typical situation is that the committee, now that they have been asked 310 | to review the proposal in detail, unearths some substantive technical issues. 311 | This is absolutely fine -- it is what the review process is *for*! 312 | 313 | If the technical debate is not rapidly resolved, the shepherd 314 | should return the proposal for revision. Further technical 315 | discussion can then take place, the author can incorporate that 316 | conclusions in the proposal itself, and re-submit it. Returning a 317 | proposal for revision is not a negative judgement; on the contrary 318 | it might connote "we absolutely love this proposal but we want it 319 | to be clear on these points". 320 | 321 | In fact, this should happen if *any* substantive technical debate 322 | takes place. The goal of the committee review is to say yes/no to a 323 | proposal *as it stands*. If new issues come up, they should be 324 | resolved, incorporated in the proposal, and the revised proposal 325 | should then be re-submitted for timely yes/no decision. In this way, 326 | *no proposal should languish in the committee review stage for long*, 327 | and every proposal can be accepted as-is, rather than subject to a raft 328 | of ill-specified further modifications. 329 | 330 | The author of the proposal may invite committee collaboration on clarifying 331 | technical points; conversely members of the committee may offer such help. 332 | 333 | When a proposal is returned for revision, GitHub labels are updated accordingly 334 | and the ``(under review)`` suffix is removed from the title of the PR. 335 | 336 | - The decision is announced, by the shepherd or the secretary, on the Github 337 | thread and the mailing list. 338 | 339 | Notwithstanding the return/resubmit cycle described above, it may be 340 | that the shepherd accepts a proposal subject to some specified minor changes 341 | to the proposal text. In that case the author should carry them out. 342 | 343 | The secretary then tags the pull request accordingly, and either 344 | merges or closes it. In particular 345 | 346 | * **If we say no:** 347 | The pull request will be closed and labeled 348 | `Rejected `_. 349 | 350 | If the proposer wants to revise and try again, the new proposal should 351 | explicitly address the rejection comments. 352 | 353 | In the case that the proposed change has already been implemented in 354 | the library, it will be reverted. 355 | 356 | * **If we say yes:** 357 | The pull request will be merged and labeled 358 | `Accepted `_. 359 | Its meta-data will be updated to include the acceptance date. 360 | A link to the accepted proposal is added to the top of the PR discussion, together with 361 | the sentence “The proposal has been accepted; the following discussion is mostly of historic interest.”. 362 | 363 | At this point, the proposal process is technically 364 | complete. It is outside the purview of the committee to implement or 365 | oversee implementation. The committee may help attract implementors, 366 | but there is no guarantee of this. 367 | 368 | The proposal authors or other implementors are encouraged to update the 369 | proposal with the implementation status (i.e. ticket URL and the 370 | first version of the library implementing it.) 371 | 372 | Concretely, a committee member must perform the following steps: 373 | 374 | 1. Add a new commit on top of the PR branch that: 375 | 376 | a. Changes the filename of the proposal to correspond to the PR number. 377 | 378 | b. Updates any metadata fields that may have changed in the template on ``master`` since 379 | the PR branch split off. 380 | 381 | c. Fills in these metadata fields as appropriate, including changing "is discussed" 382 | to "was discussed". 383 | 384 | 2. Merge the PR branch into master, and push. 385 | 386 | 3. Update the PR description to start 387 | with the text "The proposal has been accepted; the following discussion is mostly of historic interest." 388 | where the word "proposal" links to the final rendered version pushed above. 389 | 390 | 4. If the PR title has "(under review)", remove it. 391 | 392 | 5. Set the PR to have the "Accepted" label. 393 | 394 | 6. Comment on the PR that the proposal was accepted. 395 | 396 | 7. Close the PR if GitHub has not detected the merge. 397 | 398 | 8. Announce on the committee mailing list. 399 | 400 | Review criteria 401 | --------------- 402 | Here are some characteristics that a good proposal should have. 403 | 404 | * *It should be self-standing*. Some proposals accumulate a long and interesting discussion 405 | thread, but in ten years' time all that will be gone (except for the most assiduous readers). 406 | Before acceptance, therefore, the proposal should be edited to reflect the fruits of 407 | that dicussion, so that it can stand alone. 408 | 409 | * *It should be precise*, especially the "Proposed change specification" 410 | section. Library/API design is complicated, with lots of 411 | interactions. It is not enough to offer a few suggestive examples 412 | and hope that the reader can infer the rest. Vague proposals waste 413 | everyone's time; precision is highly valued. 414 | 415 | We do not insist on a fully formal specification, with a 416 | machine-checked proof. There is no such baseline to work from, and 417 | it would set the bar far too high. 418 | 419 | Ultimately, the necessary degree of precision is a judgement that the committee 420 | must make; but authors should try hard to offer precision. 421 | 422 | * *It should offer evidence of utility*. Even the strongest proposals carry costs: 423 | 424 | * For programmers: most proposals make the API just a bit more complicated; 425 | * For library maintainers: most proposals make the implementation a bit more complicated; 426 | * For future proposers: most proposals add new back-compat burdens, which makes new proposals harder to fit in. 427 | * It is much, much harder subsequently to remove a change than it is to add it. 428 | 429 | All these costs constitute a permanent tax on every future programmer and library maintainer. 430 | The tax may well be worth it, but the case should be made. 431 | 432 | The case is stronger if lots of people express support by giving a "thumbs-up" 433 | in GitHub. Even better is the community contributes new examples that illustrate 434 | how the proposal will be broadly useful. 435 | The committee is often faced with proposals that are reasonable, 436 | but where there is a suspicion that no one other than the author cares. 437 | Defusing this suspicion, by describing use-cases and inviting support from others, 438 | is helpful. 439 | 440 | * *It should be copiously illustrated with examples*, to aid understanding. However, 441 | these examples should *not* be the specification. 442 | 443 | Below are some criteria that the committee and the supporting Haskell 444 | community will generally use to evaluate a proposal. These criteria 445 | are guidelines and questions that the committee will consider. 446 | None of these criteria is an absolute bar: it is the committee's job to weigh them, 447 | and any other relevant considerations, appropriately. 448 | 449 | - *Utility and user demand*. What exactly is the problem that the 450 | feature solves? Is it an important problem, felt by many users, or is 451 | it very specialised? The whole point of a new feature is to be useful 452 | to people, so a good proposal will explain why this is so, and 453 | ideally offer evidence of some form. The "Endorsements" section of 454 | the proposal provides an opportunity for third parties to express 455 | their support for the proposal, and the reasons they would like to 456 | see it adopted. 457 | 458 | - *Elegant and principled*. Haskell is a beautiful and principled 459 | language. It is tempting to pile feature upon feature, but we 460 | should constantly and consciously strive for simplicity and elegance. 461 | 462 | This is not always easy. Sometimes an important problem has lots of 463 | solutions, none of which have that "aha" feeling of "this is the Right 464 | Way to solve this"; in that case we might delay rather than forge ahead 465 | regardless. 466 | 467 | - *Does not create a library fork*. By a "fork" we mean 468 | 469 | * It fails the test "Is this something that most people would be happy to use, if the need arises?"; 470 | * In the case of a module dictated by the Haskell Report; it also fails the test "Do we think there's a reasonable chance this change will make it into a future Report?"; that is, the proposal reflects the stylistic preferences of a subset of the Haskell community, rather than a consensus about the direction that (in the committee's judgement) we want to push the Report. 471 | 472 | - *Fit with the ecosystem.* If we just throw things into core libraries 473 | willy-nilly, they will become large balls of incoherent and 474 | inconsistent mud. We strive to make additions that are consistent with 475 | the rest of the ecosystem. 476 | 477 | - *Specification cost.* Does the benefit of the feature justify the 478 | extra complexity in the API specification? Does the new feature 479 | interact awkwardly with existing features, or does it enhance them? 480 | How easy is it for users to understand the new feature? 481 | 482 | - *Implementation cost.* How hard is it to implement? 483 | 484 | - *Maintainability.* Writing code is cheap; maintaining it is 485 | expensive. The core libraries are very large pieces of software, with 486 | lifetimes stretching over decades. It is tempting to think that if you propose 487 | a feature *and* offer a patch that implements it, then the 488 | implementation cost to the library is zero and the patch should be accepted. 489 | 490 | But in fact every new feature imposes a tax on future implementors, (a) 491 | to keep it working, and (b) to understand and manage its interactions 492 | with other new features. In the common case the original implementor of 493 | a feature moves on to other things after a few years, and this 494 | maintenance burden falls on others. 495 | 496 | How to build the proposals? 497 | --------------------------- 498 | 499 | The proposals can be rendered by running:: 500 | 501 | nix-shell shell.nix --run "make html" 502 | 503 | this will then create a directory ``_build`` which will contain an ``index.html`` 504 | file and the other rendered proposals. This is useful when developing a proposal 505 | to ensure that your file is syntax correct. 506 | 507 | 508 | Questions? 509 | ---------- 510 | 511 | Feel free to contact any of the members of the `Core Libraries Committee 512 | <#who-is-the-committee>`_ with questions. `Email `_ 513 | is a good way of accomplishing this. 514 | --------------------------------------------------------------------------------