This repository contains specifications for proposed changes to Hail. The purpose of the Hail rfc process is to broaden the discussion of the evolution of Hail.
A Hail RFC is a document describing a proposed change to Hail query, batch, CI or any systems under hail.
Proposals are written in ReStructuredText.
Proposals should follow the structure given in the ReStructuredText template.
See the section Review criteria below for more information about what makes a strong proposal, and how it will be reviewed.
To start a proposal, create a pull request that adds your proposal as
proposals/0000-proposal-name.rst. Use the corresponding
proposals/0000-template.rst 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).
- 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)Some proposals amend an existing proposal. Such an amendment :
- Makes a significant (i.e. not just editorial or typographical) change, and hence warrants approval by the Hail team
- Is too small, or too closely tied to the existing proposal, to make sense as a new standalone proposal.
Often, this happens after a proposal is accepted, but before or while it is implemented. In these cases, a PR that _changes_ the accepted proposal can be opened. It goes through the same process as an original proposal.
Members of the Hail 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.
Here are some characteristics that a good proposal should have.
It should be self-standing. Some proposals accumulate a long and interesting discussion thread, but in ten years' time all that will be gone (except for the most assiduous readers). Before acceptance, therefore, the proposal should be edited to reflect the fruits of that discussion, so that it can stand alone.
It should be precise, especially the "Proposed change specification" section. Language design is complicated, with lots of interactions. It is not enough to offer a few suggestive examples and hope that the reader can infer the rest. Vague proposals waste everyone's time; precision is highly valued.
We do not insist on a fully formal specification. There is no such baseline to work from, and it would set the bar far too high.
Ultimately, the necessary degree of precision is a judgement that the Hail team must make; but authors should try hard to offer precision.
It should offer evidence of utility. Even the strongest proposals carry costs:
- For programmers: most proposals make the language just a bit more complicated;
- For maintainers: most proposals make the implementation a bit more complicated;
- For future proposers: most proposals consume syntactic design space add/or add new back-compat burdens, both of which make new proposals harder to fit in.
- It is much, much harder subsequently to remove an extension than it is to add it.
All these costs constitute a permanent tax on every future programmer, language designer, and maintainer. The tax may well be worth it (a language without polymorphism would be simpler but we don't want it), but the case should be made.
The case is stronger if lots of people express support by giving a "thumbs-up" in GitHub. Even better is the community contributes new examples that illustrate how the proposal will be broadly useful. The Hail team is often faced with proposals that are reasonable, but where there is a suspicion that no one other than the author cares. Defusing this suspicion, by describing use-cases and inviting support from others, is helpful.
It should be copiously illustrated with examples, to aid understanding. However, these examples should not be the specification.
Below are some criteria that the Hail team and the supporting community will generally use to evaluate a proposal. These criteria are guidelines and questions that the Hail team will consider. None of these criteria is an absolute bar: it is the Hail team's job to weigh them, 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. The "Endorsements" section of the proposal provides an opportunity for third parties to express their support for the proposal, and the reasons they would like to see it adopted.
Elegant and principled. It is tempting to pile feature upon feature, but we should constantly and consciously strive for simplicity.
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.
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. Hail is a large piece of software maintained by a small team. It is tempting to think that if you propose a feature and offer a patch that implements it, then the implementation cost to Hail 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:
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 Hail team. See get help on the website for details.
The structure, wording, templates and configurations has been lifted from ghc-proposals/ghc-proposals.