This repository contains specifications for proposed changes to the Glasgow Haskell Compiler. The purpose of the GHC proposal process and of the GHC Steering Committee, is to broaden the discussion of the evolution of GHC.
- ≡ List of proposals under discussion
- ≡ List of proposals waiting for shepherd recommendation
- ≡ List of proposals waiting for committee decision
- ≡ List of accepted proposals
- ≡ List of rejected proposals
- ≡ List of implemented proposals
- ≡ List of all proposals
The author drafts a proposal.
The author submits the proposal to the wider Haskell community for discussion, as a pull request against this repository.
The wider community discusses the proposal in the commit section of the pull request, while the author refines the proposal. This phase lasts as long as necessary.
Discussion goals • How to comment on a proposal • ≡ List of proposals under discussion
Eventually the proposal author brings the proposal before the committee for review.
How to bring a proposal before the committee • Who is the committee?
One committee member steps up as a shepherd, and generates consensus within the committee within four or five weeks.
Committee process • Review criteria • ≡ List of proposals waiting for shepherd • ≡ List of proposals under review
Eventually, the committee rejects a proposal, or passes it back to the author for review, or accepts it.
Acceptance of the proposal implies that the implementation will be accepted into GHC provided it is well-engineered, well-documented, and does not complicate the code-base too much.
If a proposal sees no activity for along time, they are marked as “dormant”, and eventually closed.
Once a proposal is accepted, it still has to be implemented. The author may do that, or someone else. We mark the proposal as “implemented” once it hits GHC’s
masterbranch (and we are happy to be nudged to do so by email or GitHub issue).
Do not hesitate to contact us if you have questions.
A GHC Proposal is a document describing a proposed change to the compiler, the
GHC/Haskell language, or the libraries in the GHC.* module namespace. These
include,
- A syntactic change to GHC/Haskell (e.g. the various
ShortImportsproposals,doexpressions without$) - A major change to the user-visible behaviour of the compiler (e.g. the recent
change in super-class
solving, and
-Wallbehavior) - The addition of major features to the compiler (e.g.
-XTypeInType, GHCi commands, type-indexedTypeablerepresentations)
Changes to the GHC API or the plugin API are not automatically within the scope of the committee, and can be contributed following the usual GHC workflow. Should the GHC maintainers deem a change significant or controversial enough to warrant that, they may, at their discretion, involve the committee and ask the contributor to write a formal proposal.
Each proposal document must follow the following outline. Templates are available for both ReStructuredText, and Markdown.
- Motivation: Give a strong reason for why the community needs this change. Describe the use case as clearly as possible and give at least one concrete example. Explain how the status quo is insufficient or not ideal.
- Proposed Change Specification: Specify the change in precise and comprehensive yet concise language. Your specification may include,
- grammar and semantics of any new syntactic constructs
- the types and semantics of any new library interfaces
- how the proposed change addresses the original problem (perhaps referring back to the example)
The change should be phrased relative to the Haskell report and/or the GHC user manual. Do not assume familiarity with the implementation, and avoid referncing the implementation.
- Effect and Interactions. Detail how the proposed change addresses the original problem raised in the motivation. Detail how the proposed change interacts with existing language or compiler features. Think about what surprising or problematic interactions may occur.
- Costs and Drawbacks. What are the drawbacks and costs to the community should this change be implemented? For example, does this make Haskell harder to learn for novice users? Does it make Haskell code harder to read or reason about? Will the implementation be complex or invasive?
- Alternatives: List alternatives to your proposed change and discuss why they are insufficient.
- Unresolved questions: Explicitly list any remaining issues that remain in the conceptual design and specification. Be upfront and trust that the community will help. Please do not list implementation issues.
- Implementation Plan (Optional): If accepted who will implement the change? It's quite okay to say "unknown" if you don't feel willing or able to carry out the implementation yourself.
This is also a good section to outline the changes to the implementation, or otherwise include insights that assume familiarity with the implementation.
Proposals are written in either ReStructuredText or Markdown. While the proposal process itself has no preference, keep in mind that the GHC Users Guide uses ReStructuredText exclusively. Accepted proposals written in ReStructuredText thus have the slight benefit that they can be more easily included in the official GHC documentation.
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.
If you are unfamiliar with git and github, you can use the GitHub web interface to perform these steps:
- Load the proposal template using this link (ReStructuredText) or this link (Markdown).
- Change the filename and edit the proposal.
- Press “Commit new file”
The pull request summary should include a brief description of your proposal, along with a link to the rendered view of proposal document in your branch. For instance,
This is a proposal augmenting our existing `Typeable` mechanism with a
variant, `Type.Reflection`, which provides a more strongly typed variant as
originally described in [A Reflection on
Types](http://research.microsoft.com/en-us/um/people/simonpj/papers/haskell-dynamic/index.htm)
(Peyton Jones, _et al._ 2016).
[Rendered](https://github.com/bgamari/ghc-proposals/blob/typeable/proposals/0000-type-indexed-typeable.rst)Members of the Haskell community are warmly invited to offer feedback on proposals. Feedback ensures that a variety of perspectives are heard, that alternative designs are considered, and that all of the pros and cons of a design are uncovered. We particularly encourage the following types of feedback,
- Completeness: Is the proposal missing a case?
- Soundness: Is the specification sound or does it include mistakes?
- Alternatives: Are all reasonable alternatives listed and discussed. Are the pros and cons argued convincingly?
- Costs: Are the costs for implementation believable? How much would this hinder learning the language?
- Other questions: Ask critical questions that need to be resolved.
- Motivation: Is the motivation reasonable?
To comment on a proposal you need to be viewing the proposal's diff in "source diff" view. To switch to this view use the buttons on the top-right corner of the Files Changed tab.
Use the view selector buttons on the top right corner of the "Files Changed" tab to change between "source diff" and "rich diff" views.
Feedback on a open pull requests can be offered using both GitHub's in-line and pull request commenting features. Inline comments can be added by hovering over a line of the diff.
Hover over a line in the source diff view of a pull request and
click on the + to leave an inline comment
For the maintenance of general sanity, try to avoid leaving "me too" comments. If you would like to register your approval or disapproval of a particular comment or proposal, feel free to use GitHub's "Reactions" feature.
When the discussion has ebbed down and the author thinks the proposal is ready, he
- reviews the discussion thread and ensure that the proposal text accounts for all salient points.
- adds a comment to the a pull request, briefly summarizing the major points raised
during the discussion period and stating your belief that the proposal is
ready for review. In this comment, tag the committee secretary (currently
@nomeata).
The secretary will then label the pull request with
Pending shepherd recommendation and start the committee process. (If this does not happen within a day or two, please
ping the secretary or the committee.)
In order to keep better track of actively discussed proposals, proposals that
see no activity for an extended period of time (a month or two) might be marked
as “dormant”. At any time the proposer, or someone else can revive the
proposal by picking up the discussion (and possibly asking the secretary to remove the dormant tag).
You can see the list of dormant proposals.
You can reach the committee by email at ghc-steering-committee@haskell.org:
The current members, including their GitHub handle, when they joined and their role, are listed at:
| Christopher Allen | @bitemyapp | 2017/02 | |
| Vitaly Bragilevsky | @bravit | 2018/09 | |
| Joachim Breitner | @nomeata | 2017/02 | secretary |
| Iavor Diatchki | @yav | 2017/02 | |
| Richard Eisenberg | @goldfirere | 2017/02 | |
| Sandy Maguire | @isovector | 2019/07 | |
| Simon Marlow | @simonmar | 2017/02 | co-chair |
| Simon Peyton-Jones | @simonpj | 2017/02 | co-chair |
| Eric Seidel | @gridaphobe | 2018/09 | |
| Arnaud Spiwack | @aspiwack | 2019/07 |
The committee members have committed to adhere to the Haskell committee guidelines for respectful communication.
We would also like to thank our former members:
| Ryan Newton | @rrnewton | 2017/02 - 2018/09 |
| Roman Leshchinskiy | @rleshchinskiy | 2017/02 - 2018/11 |
| Ben Gamari | @bgamari | 2017/02 - 2019/07 |
| Manuel M T Chakravarty | @mchakravarty | 2017/02 - 2019/07 |
The committee process starts once the secretary has been notified that a proposal is ready for decision.
The secretary nominates a member of the committee, the shepherd, to oversee the discussion. The secretary
- labels the proposal as
Pending shepherd recommendation, - assigns the proposal to the shepherd,
- drops a short mail on the mailing list, informing the committee about the status change.
- labels the proposal as
Based on the proposal text (but not the GitHub commentary), the shepherd decides whether the proposal ought to be accepted or rejected or returned for revision.
If the shepherd thinks the proposal ought to be rejected, they post their justifications on the GitHub thread, and invite the authors to respond with a rebuttal and/or refine the proposal. This continues until either
- the shepherd changes their mind and supports the proposal now,
- the authors withdraw their proposal,
- the authors indicate that they will revise the proposal to address the shepherds point. The shepherd will label the pull request as Needs Revision.
- the authors and the shepherd fully understand each other’s differing positions, even if they disagree on the conclusion.
Now the shepherd proposes to accept or reject the proposal. To do so, they
- post their recommendation, with a rationale, on the GitHub discussion thread,
- label the pull request as
Pending committee review, - notify the committee by mentioning
@ghc-proposals/ghc-steering-committee, - include the sentence “This proposal will now be discussed by the committee. We welcome all authors to join the discussion, but kindly ask others to refrain from posting.” in the comment
- drop a short mail to the mailing list informing the committee that discussion has started.
Discussion among the committee ensues on the discussion thread. Silence is understood as agreement with the shepherd's recommendation. Ideally, the committee reaches consensus, as determined by the secretary or the shepherd. If consensus is elusive, then we vote, with the Simons retaining veto power.
The decision is announced, by the shepherd or the secretary, on the Github thread and the mailing list.
The secretary tags the pull request accordingly, and either merges or closes it. In particular
If we say no: The pull request will be closed and labeled Rejected.
If the proposer wants to revise and try again, the new proposal should explicitly address the rejection comments.
In the case that the proposed change has already been implemented in GHC, it will be reverted.
If we say yes: The pull request will be merged and labeled Accepted. Its meta-data will be updated to include the acceptance date. A link to the accepted proposal is added to the top of the PR discussion, together with the sentence “The proposal has been accepted; the following discussion is mostly of historic interest.”.
At this point, the proposal process is technically complete. It is outside the purview of the committee to implement, oversee implementation, attract implementors, etc.
The proposal authors or other implementors are encouraged to update the proposal with the implementation status (i.e. ticket URL and the first version of GHC implementing it.)
Below are some criteria that the committee and the supporting GHC community will generally use to evaluate a proposal. Note that this list is merely set of a guidelines; it is the committee's job to weigh these and any other relevant considerations appropriately.
Utility and user demand. What exactly is the problem that the feature solves? Is it an important problem, felt by many users, or is it very specialised? The whole point of a new feature is to be useful to people, so a good proposal will explain why this is so, and ideally offer evidence of some form.
Elegant and principled. Haskell is a beautiful and principled language. It is tempting to pile feature upon feature (and GHC Haskell has quite a bit of that), but we should constantly and consciously strive for simplicity and elegance.
This is not always easy. Sometimes an important problem has lots of solutions, none of which have that "aha" feeling of "this is the Right Way to solve this"; in that case we might delay rather than forge ahead regardless.
Fit with the language. If we just throw things into GHC willy-nilly, it will become a large ball of incoherent and inconsistent mud. We strive to add features that are consistent with the rest of the language.
Specification cost. Does the benefit of the feature justify the extra complexity in the language specification? Does the new feature interact awkwardly with existing features, or does it enhance them? How easy is it for users to understand the new feature?
Implementation cost. How hard is it to implement?
Maintainability. Writing code is cheap; maintaining it is expensive. GHC is a very large piece of software, with a lifetime stretching over decades. It is tempting to think that if you propose a feature and offer a patch that implements it, then the implementation cost to GHC is zero and the patch should be accepted.
But in fact every new feature imposes a tax on future implementors, (a) to keep it working, and (b) to understand and manage its interactions with other new features. In the common case the original implementor of a feature moves on to other things after a few years, and this maintenance burden falls on others.
The proposals can be rendered by running:
nix-shell shell.nix --run "make html"
this will then create a directory _build which will contain an index.html
file and the other rendered proposals. This is useful when developing a proposal
to ensure that your file is syntax correct.
Feel free to contact any of the members of the GHC Steering Committee with questions. Email
and IRC (#ghc on irc.freenode.net) are both good ways of accomplishing this.