New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

A new process for GHC proposals #1

Merged
merged 13 commits into from Sep 27, 2016
View
@@ -70,21 +70,28 @@ process, here is a short summary,
1. Clone this repository and create a branch in your clone for your new proposal.
2. Starting with the `template <https://github.com/bgamari/ghc-proposals/blob/master/0000-template.rst>`_,
describe your proposed change in a file in the ``proposals/`` directory.
describe your proposed change in a file in the ``proposals/`` directory. Use
a filename of the form ``proposals/0000-short-proposal-title.rst``.
3. When you feel your proposal document is complete, open a ``Pull Request``
3. Write down the details of your proposal. At very least this will involve
filling in the empty fields of the template. Note that proposals are written
in `ReStructuredText <http://www.sphinx-doc.org/en/stable/rest.html>`_, not
Markdown, for its expressiveness and ease of integration into other GHC
infrastructure.
4. When you feel your proposal document is complete, open a ``Pull Request``
requesting that your branch be merged into the ``master`` branch of this
repository. Be sure to include a link to the rendered view of your proposal
in the pull request description. Your proposal will automatically be
announced on the ``ghc-devs`` mailing list when this pull request is opened.
4. Discussion will proceed on the pull request; it is very likely that multiple
5. Discussion will proceed on the pull request; it is very likely that multiple
iterations will be necessary before the proposal stabilizes.
5. When discussion has died down email the (yet to be formed) GHC Commitee , who
6. When discussion has died down email the (yet to be formed) GHC Commitee , who
will review the proposal, the feedback collected on the pull request, and
general community sentiment and decide whether the proposal will be accepted.
6. When your proposal is accepted your pull request will be merged. At this
7. When your proposal is accepted your pull request will be merged. At this
point you or someone else may choose to implement your proposal.
@@ -0,0 +1,319 @@
**This proposal is open for community comments!** Please let us know what you
think about the proposed protocol by leaving a comment on the GitHub pull
request associated with the proposal by clicking on the "Conversation" tab above.
A Proposal for Proposals
========================
.. contents::
Recently there has been a growing feeling within the Haskell community that the
mechanisms for proposing features and changes to GHC and the language that it
compiles are less than approachable. In particular our tools for managing the
proposal specifications and surrounding discussions make participation harder
than necessary. Over the last few weeks I have been looking at how other
open-source compiler projects address these issues (focusing on LLVM, Python,
and Rust) with an eye towards improving GHC's own practices.
To be clear, the process discussed below only affects proposal of the following
three classes,
* A syntactic change to GHC Haskell (e.g. the various ``ShortImports``
`proposals <https://ghc.haskell.org/trac/ghc/ticket/10478>`_, ``do``
`expressions <https://ghc.haskell.org/trac/ghc/ticket/10843>`_ without ``$``)
* A major change to the user-visible behaviour of the compiler (e.g. the recent
`change <https://ghc.haskell.org/trac/ghc/ticket/11762>`_ in super-class
solving, and ``-Wall`` `behavior <https://ghc.haskell.org/trac/ghc/ticket/11370>`_)
* The addition of major features to the compiler (e.g. ``-XTypeInType``, GHCi
`commands <https://ghc.haskell.org/trac/ghc/ticket/10874>`_,
`type-indexed <https://ghc.haskell.org/trac/ghc/wiki/Typeable>`_
``Typeable`` representations)
* The removal of major features from the compiler

This comment has been minimized.

@phadej

phadej Jul 14, 2016

Contributor

We could list some classes which clearly falls out of the scope of this process.

Rust lists e.g.

  • Additions only likely to be noticed by other developers-of-rust, invisible to users-of-rust.
  • Additions that strictly improve objective, numerical quality criteria (warning removal, speedup, better platform coverage, more parallelism, trap more errors, etc.) (I can think e.g. about GADT pattern matching exhaustiveness checker)
Note that this process does not cover,
* *Bug fixes to GHC that do not imply major semantic changes*: There is little
benefit for these to be treated with a formal process; existing code review
processes are quite sufficient.
* *Changes to the Haskell Report*: Language standardization has rather different
needs from the more exploratory proposals which GHC often entertains. Language
standards are formal specifications which only describes very well-understood
features; consequently the revision duration is significantly longer than the
typical GHC feature proposal. For this reason, it makes sense to keep
responsibility over standardization where it lies currently, with the Haskell
Prime Committee.
* *Changes to the core libraries*: While there is often significant overlap
between language design and library design, we are going to declare this out
of scope for the time being.
Motivation
----------
Let's start by examining a few of the shortcomings of GHC's current
change management processes,
1. Higher than necessary barrier-to-entry.
Involving oneself in the proposal process requires following a Trac ticket,
a Wiki page, one or more mailing list threads, and possibly Phabricator,
each of which requires a separate account
2. The proposal itself and the discussion surrounding it are quite decoupled.
The proposal specification itself is kept on the Trac Wiki, design
discussion occurs in largely independent Trac tickets, and further
discussion is fragmented across several mailing lists, Reddit, and IRC. This
leads to repetitive and often difficult-to-follow discussions.
3. The phases of the lifecycle of a proposal are not clearly defined.
This leads to unfortunate cases like that of ``ShortImports``, where
discussion proceeds for too long without a concrete specification. This
drains effort from both the author of the proposal and those discussing it.
4. The process that exists isn't always consistently applied.
While this arguably has improved in recent years, there are cases where
features have been added without a formal specification or perhaps less
discussion than would be desired.
Proposed change
---------------
I propose that we adopt a variant on the
`Rust RFC scheme <https://github.com/rust-lang/rfcs#what-the-process-is>`_,
building our proposal process on top of existing code review tools for
dissemination and refinement of proposals with a standing committee acting as
the final arbiter of proposal acceptance.
To ensure that the process is as accessible and convenient as possible, I
propose that we build this process on top of GitHub.
Proposal process
~~~~~~~~~~~~~~~~
Each proposal goes through the following stages:
1. The process begins with the opening of a pull request to the GHC proposals
repository, proposing the merge of a document (derived from a
`provided template <https://github.com/ghc-proposals/ghc-proposals/blob/master/0000-template.rst>`_)
specifying the proposed change. This document is the primary specification
of the feature and takes the place of the current Trac Wiki document.
2. Community members (including members of the proposal committee) will discuss

This comment has been minimized.

@acfoltzer

acfoltzer Jul 20, 2016

What is the proposal committee referred to here?

edit: After reading further, I'm inferring that it's the GHC committee below. This probably just needs to be clarified for folks reading top-to-bottom

This comment has been minimized.

@bgamari

bgamari Aug 2, 2016

Contributor

I believe this is addressed in the "Proposed change" section.

the proposal. The submitter is responsible for amending the specification to
account for collected comments. It should be expected that the proposal will
change during this process, which may last from days to months.
3. When the author feels that the proposal is complete, and not being improved
by further discussion, they can submit the proposal to the proposal committee
for a decision.
4. Within two (exceptionally three) weeks the committee will arrive at a
consensus as to whether the proposal in its submitted form meets a set of
criteria for inclusion (see below) while weighing the opinions expressed by
the community.
If the proposal is rejected then it will be sent back to the submitter along
with a rationale (referencing the criteria defined below). This is by no
means a final decision; the submitter may at any time amend and re-submit the
proposal to address the concerns of the committee.
5. When the proposal is accepted the pull request will be merged and the
document will be preserved in the proposals repository as a permanent
specification for the feature.
6. The author will create a Trac ticket linking to the proposal to
provide a place track the progress of the implementation.
7. The author may choose to implement the proposal after acceptance, but she is
under no obligation to do so. (Of course, neither is anyone else.)
8. During implementation, it is very likely that the specification will be refined.
The implementor should keep the specification up to date over the course of
the implementation.
Since the proposal pages already existing on the Trac `Wiki
<https://ghc.haskell.org/trac/ghc/wiki/Proposal>`_ represent a significant
amount of effort and knowledge, we'll make an effort to import those which have
been implemented into the proposals repository if this scheme is adopted.
GHC Committee
~~~~~~~~~~~~~
The process involves forming a small group which is responsible for
deciding whether proposed changes should be accepted after discussion
within the community.
The committee should be large enough to reflect the diversity of GHC's
contributor- and user-base but small enough to ensure a sense of individual
responsibility among its members. A size of six to eight members would likely be
a good starting point.
To simplify the committee selection process, I propose that the committee is
chosen as follows. We seek nominations (including self-nominations); and then
Simon Peyton-Jones and Simon Marlow select members from those nominations. This

This comment has been minimized.

@phadej

phadej Jul 12, 2016

Contributor

Meta: I think we can also comment using line-comments. And we can react on those.

E.g. I also agree that Simon&Simon is a good combo to act as a chair.

is simple and clear. It is also not very democratic, but Simon & Simon did
originate GHC, and it is far from clear that a voting process would yield a

This comment has been minimized.

@spl

spl Jul 12, 2016

originate create?

better result. Moreover, voting brings with it a number of additional
complexities (e.g. who can vote? who decides who can vote? how are votes
collected?)
The group will have three roles,
* *Deciding proposal acceptance.* At the proposal author's invitation, the
committee makes the decision over whether a proposal should be accepted, in
light of a set of defined criteria (see below).
* *Judging whether the proposal process should be applied.* There will no doubt
be proposals where it is unclear whether the burden of the proposal process is
necessary. The responsibility for determining the scope of the process lies
with the committee.
* *Ensuring that the process is applied when necessary.* The committee will be
expected to monitor GHC contributions and ensure that changes which fall
within the scope of the proposal process indeed go through the process.
Criteria for new features
~~~~~~~~~~~~~~~~~~~~~~~~~
The committee is responsible for weighing a variety of factors when deciding
whether to adopt a feature. These are all judgement calls.
1. *The problem*. What exactly is the problem that the feature solves? Is
it an important problem, felt by many users, or is it very specialised?
2. *The right solution; generality*. Elegance, economy, and generality are
important. Sometimes a problem has lots of solutions, none of which have that
"aha" feeling of "this is the Right way to solve this". A classic example is
that of records, for which we have had endless proposals (including many from
the GHC authors themselves) none of which felt "right", and none of which
made it into GHC.
3. *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.
4. *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?
5. *Implementation cost*. How complex is the implementation likely to be? Is it
highly localised, or does it require pervasive changes? As an author and
contributor, it may look like you are giving GHC free work, but this
viewpoint doesn't align with the reality of a large project with a timescale
in decades. Writing code is cheap; maintaining it is expensive.
Drawbacks
---------
Of course, group decision-making processes are difficult to manage and tools
will only bring you so far. While the Rust scheme does seem to function more
smoothly than our current system, it is not free of issues (as most recently
discussed by `Aaron Turon
<https://aturon.github.io/blog/2016/07/05/rfc-refinement/>`_). These issues will
likely apply to the process proposed here as well. In particular,
* GitHub discussions in particular don't scale terribly well; the lack of
hierarchical threading means that long threads can become difficult to follow;
experience suggests that Phabricator seems to be a bit better but long
technical discussions are a challenge for nearly any tool.

This comment has been minimized.

@acfoltzer

acfoltzer Jul 20, 2016

No matter the tool, we should be mindful of the risk that limitations will prompt branching off discussion in the form of IRC chats, skype calls, etc. I'm not sure that a mechanism is appropriate to address this, but proposal committee members should try to report back the salient points of such conversations in the originating thread. One of the ways I've seen people feel excluded by the current system is when this doesn't happen.

* The ease of commenting may bring a slightly diminished signal-to-noise ratio
in collected feedback, particularly on easily bike-shedded topics.
Moreover, even leaving behind our current system incurs somewhat of a cost. Trac
already exists and a significant fraction of GHC developers are already quite
comfortable with it. The fact that we already use it for Wiki and ticket
tracking means that cross-referencing between proposals, tickets, and the Wiki
is trivial. Any replacement system would almost certainly regress in this area.
Alternatives
------------
There are a few alternatives which are worth considering,
* We continue to build on Trac, but attempt to be more rigorous with our
current protocol. Namely we attempt to better document and more consistently
enforce the procedures we currently have.
* Adopting the process discussed above but replacing GitHub with Phabricator.
This would offer the disadvantage of being slightly harder for casual
contributors. Moreover, Phabricator lacks some of GitHub's support for
formatting markup. Phabricator, however, offers the advantage of integrating
better with GHC's current Trac instance and avoid adding yet another tool to
the GHC developer's toolchain.
* Adopting the process discussed above but replacing GitHub with GitLab. GitLab
has many of the features of GitHub but with the advantage of being open-source
and self-hostable. Unfortunately it would mean introducing yet another tool
into the GHC developer's toolbelt and add yet another piece of infrastructure
to administer.
* We move to something closer to the Python PEP scheme. Here a committee is
formed for each proposal; the committee is responsible for crafting and
collecting feedback on the proposal. The final acceptance decision is made by
the Benevolant Dictator for Life. Discussion can be carried out on a medium
of the committee's choosing, with a common choice being a specially-created
mailing list.
* The Rust community has been `considering
<https://aturon.github.io/blog/2016/07/05/rfc-refinement/>`_ breaking their
process up in multiple stages to make their proposal queue more manageable. To
first order these stages are,
1. form a consensus around the problem and the need to solve it
2. propose and refine possible solutions
3. choose from among the proposed solutions
The separation of step (1) from the others gives the community a means of
concentrating focus on a set of small problems and encouraging exploration
down multiple solution avenues. The cost of this is that it may frustrate
authors with a slower, more involved process.
* Something else entirely...
Moving closer to the Rust process
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Also, there are a few facets of the Rust process which the proposed process does
not carry over for a variety of reasons:
* *Shepherds*. In the Rust process each submitted proposal is assigned a
shepherd. This is a trusted core developer who is charged with keeping the
proposal moving through the process. At the moment GHC arguably lacks the
contributor pool to guarantee this.

This comment has been minimized.

@acfoltzer

acfoltzer Jul 20, 2016

Is it necessary that a shepherd be a core developer? We certainly wouldn't want strangers in this role, but I don't think we should limit this to people with hands-on GHC hacking experience. It seems far more important to have an understanding of community norms and processes, and to know whom to consult when more technical depth is required.

This comment has been minimized.

@cartazio

cartazio Jul 20, 2016

What's a concrete difference between what this says and what the right ghc
contributors / experts would be?

Either way, I agree with Gershom, let's just try stuff and see what
happens. Anything else isn't moving the needle ;)

On Wednesday, July 20, 2016, Adam C. Foltzer notifications@github.com
wrote:

In proposals/0000-proposal-process.rst
#1 (comment)
:

  • down multiple solution avenues. The cost of this is that it may frustrate
  • authors with a slower, more involved process.

+* Something else entirely...
+
+
+Moving closer to the Rust process
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Also, there are a few facets of the Rust process which the proposed process does
+not carry over for a variety of reasons:
+
+* Shepherds. In the Rust process each submitted proposal is assigned a

  • shepherd. This is a trusted core developer who is charged with keeping the
  • proposal moving through the process. At the moment GHC arguably lacks the
  • contributor pool to guarantee this.

Is it necessary that a shepherd be a core developer? We certainly wouldn't
want strangers in this role, but I don't think we should limit this to
people with hands-on GHC hacking experience. It seems far more important to
have an understanding of community norms and processes, and to know whom to
consult when more technical depth is required.


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/ghc-proposals/ghc-proposals/pull/1/files/1c57c641f19b3f4ca00f6525dd37a44b5042f702#r71606567,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAAQwqViHdeXxKEGxvXbEmRqCKHm9hSXks5qXo2RgaJpZM4JIsl-
.

This comment has been minimized.

@acfoltzer

acfoltzer Jul 20, 2016

To me "core developer" usually means someone who is working with the code of the project on a regular basis, in addition to having the qualities mentioned above. I just want to be clear about whether that aspect is required, or if we can cast a broader net.

* *Final comment period*. The Rust process defines a portion of the proposal
lifecycle known as the "final comment period". This is a (typically one-week)
period directly before the responsible sub-team makes its decision which is
widely announced to solicit final comments from the community. This period is
omitted from the process described above; instead it is up to the proposal
submitter to ensure that sufficient discussion is solicited.
Open Questions
--------------
There are still questions regarding the desired scope of the process. While we
want to ensure that changes which affect the user-facing aspects of the compiler
are well-considered, we certainly don't want the process to become unduly
burdensome. This is a careful balance which will require care to maintain moving
forward.
Acknowledgments
---------------
Thanks to the Rust contributors ``eddyb``, ``nmatsakis``, and ``steveklabnik``
for useful discussions sharing their experiences in the Rust community. Also,
thanks to Anthony Cowley for his `persistence
<http://www.arcadianvisions.com/blog/2016/ghc-contributing.html>`_ in raising
his concerns and helpful discussions over the course of this effort.
ProTip! Use n and p to navigate between commits in a pull request.