Proposal for update to documents #33
Conversation
|
Rendered documents: |
|
Thanks for the comments @simonpj - I'll update to clarify and improve the text. |
|
@simonpj I think that I've addressed your concerns with the latest revisions. What do you think? |
|
|
||
| The aim of the HFTP process is to apply the openness and collaboration that have shaped Haskell's documentation and implementation to a process of evolving the HF and the broader Haskell ecosystem. This document captures our guidelines, commitments and expectations regarding this process. | ||
|
|
||
| ## Acceptance | ||
|
|
||
| Upon acceptance, an HFTP and its associated discussion are merged into this repository, and both serve as a historical document that details a specification and rationale for work detailed within the process. Acceptance of a proposal does not constitute a firm commitment by the Haskell Foundation to execute on the proposal, or to provide the necessary or helpful resources that were identified in the proposal. Fundamentally, acceptance indicates that the TWG believes that the Haskell ecosystem would be better off if the proposal were implemented, and that it is sufficiently well-considered. |
There was a problem hiding this comment.
I suggest re-ordering.
Upon acceptance, an HFTP and its associated discussion are merged into this repository. The accepted proposal serves both as a permanent document that details a specification, and rationale for work detailed within the process.
Fundamentally, acceptance indicates that the TWG believes that the Haskell ecosystem would be better off if the proposal were implemented, and that it is sufficiently well-considered.
However, acceptance of a proposal does not constitute a firm commitment by the Haskell Foundation to execute on the proposal, or to provide the necessary or helpful resources that were identified in the proposal.
Actually I'm not sure what "The accepted proposal serves both as a permanent document that details a specification, and rationale for work detailed within the process." means precisely. Shall we just omit it entirely?
There was a problem hiding this comment.
That sounds good to me. I want to be explicit rather than implicit, but this text survived my edits without me really getting what it meant either. So I think it should go, or be revised if I've missed something important.
There was a problem hiding this comment.
I read that sentence as a rationale for keeping the proposals around in the repo (as opposed to, say, storing them privately somewhere). That said, I don't think there's much controversy here, and so I don't the sentence as adding much.
|
|
||
| ## Submission process summary | ||
|
|
||
| 1. Submit a Pre-HFTP topic to [Discourse](https://discourse.haskell.org), soliciting informal feedback. |
There was a problem hiding this comment.
I would really like to say that the author is free to fork the repo and create a proposal, but not make a PR, in order to provide a document for the pre-HFTP discussion to look at. I.e. as part of step 1. Yes, someone could make a Google doc and socialise that, and then transfer it to the repo in step 2, but that is just bureaucratic busy-work.
There was a problem hiding this comment.
I actually would prefer that discourse posts be more of the character of "I'd like to build a WIDGET that will help Haskell in these ways. Has anyone else made the WIDGET? Am I missing something important?" rather than "Here's my long formal document that I've put lots of time into. Please comment both here and in the repo, and let's scatter our discussion."
Basically, I think that if you've already put in the time to write a long detailed document, then you're past the point where the Discourse discussion has the most potential to be helpful. Doubly so for people not as well-connected and comfortable with long-form formal writing as you.
What do you think?
There was a problem hiding this comment.
If you are saying "It's a formal requirement that you solicit feedback based on a 3-line summary to Discourse" then fine -- but I'm not sure it's worth formalising.
I would rather we do what we do on the GHC Proposals process.
- The author creates a proposal, in the repo, and invites feedback from the commuinty
- A sometimes-extensive discussion follows, typically with multiple revisions of the proposal. The committee are free to contribute, but have no obligation to do so.
- Finally the author thinks they are done, and submits the refined proposal to the committee. At that point the committee has an obligation to get involved.
At every stage there is a proposal to discuss, which helps to focus the discussion to be about what the author is acutally proposing, rather than about what the audience fantasises that they might be proposing.
A sensible author will not invest a huge amount of time in a proposal and only then share it and solicit feedback. More typcially they'll start with a sketch. But that's up to them. They are free to do a big up-front investment if they want.
The key goal is that by the time it gets to the committee, the wider community has had ample chance to discuss, reivew, say "oh I did that last year" or whatever.
It would be fine to require a post to Discourse advertising the work. But I think it should be fine for the post to say "I've written this sketch proposal, please comment there" or "I've written this detailed proposal, please comment there". I'm just asking please let's not prevent or discourage authors from writing as detailed a proposal as they please in the same format as they will ultimately submit it, as a way to generate and focus the discussion they want.
There was a problem hiding this comment.
I think the history is very relevant here.
In our early days, the HF came up with several ideas and started to pursue them. Some of these ideas overlapped substantially or incidentally with other community projects. Accordingly, some in our community felt miffed that their work wasn't built on / some worried that HF was engaging in a lot of NIH. The proposal document here was written after we had made this mistake several times, and my understanding is that the Pre-HFTP process was meant to avoid it.
I think it can be helpful to distinguish internal proposals from externally contributed proposals. That is, if a community member -- not affiliated with the HF -- posts a proposal here that overlaps with another community project, then folks can chime in and work out how the two projects overlap and whether the new idea is worth pursuing in context. This doesn't seem to cause much trouble. On the other hand, if an HF person posts a proposal here, then my sense is that the community expects that the proposal will be accepted (as the posting itself will be perceived to be the culmination of much internal discussion). Such a proposal overlapping with a community project may cause the damage the Pre-HFTP step was meant to prevent.
So a key question for me is: will we post HF-internal ideas as proposals here? That is, suppose the TWG comes up with a whiz-bang idea in one of their meetings, unrelated to an existing proposal. Everybody roughly likes the idea. Does it become a proposal? If so, a background check beforehand, on Discourse, would seem to offer reputational protection (and is otherwise a good idea). On the other hand, if such a discussion just ends up on the ED's desk without going through the proposal process, the Pre-HFTP step seems unnecessary. Hopefully the ED will do the prior art search, too! Part of the problem, though, is that the prior art step was skipped several times by several different people.
Looking at this another way: if proposals that could reasonably be seen as internal are clearly marked with their status ("we have no idea whether this is good -- just throwing it on the wall to see if it sticks" or "we really think something like this is an idea to pursue, but we need help figuring out the right way forward" or "we're pretty sure we know what we want, but the wisdom of the crowd may help us tune the details" or "we know exactly what we want, but our processes say we have to post here"), that would help enormously (in my view).
Perhaps most simply: My understanding is that the Pre-HFTP step was put into place as a checklist item for HF folks to go through before posting their own proposals. Experience suggests we need some formality around internal proposals, but it's unclear whether this step is the best way to solve this problem, especially as it puts a burden on outside contributors.
| * Use [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax) to write your HFTP. | ||
| 4. Commit your changes to your forked repository | ||
| 5. Create a new [pull request](https://github.com/haskellfoundation/tech-proposals/pull/new). | ||
| 6. Notify the TWG on Github using the team label `@haskellfoundation/tech-proposals`. Optionally, the address the `#tech-track` channel on the HF Slack instance or on Discourse (or both!). |
There was a problem hiding this comment.
Combine 5 and 6, thus
- Submit the proposal to the TWG by
- Creating a new pull request...
- Notifying the TWG
There was a problem hiding this comment.
Good idea.
| @@ -1,10 +1,29 @@ | |||
| An HFTP (*Haskell Foundation Technical Proposal*) is a process for submitting a proposal for a technical initiative to that will be executed under the guidance of the Haskell Foundation (HF). This document describes how the community may propose, discuss, and implement technical initiatives to be carried out through the Haskell Foundation that will affect the Haskell ecosystem. Each HFTP goes through an iterative process in which it is discussed by the HF Technical Track (HFTT), the broader community, and any and all interested stakeholders. If a consensus is reached, the initiative is accepted and may then be executed by the Foundation (resources permitting). Only upon reaching a consensus are initiatives accepted and executed. Upon acceptance, an HFTP and its associated discussion are merged into this repository, and both serve as a historical document that details a specification and rationale for work detailed within the process. | |||
There was a problem hiding this comment.
Please can we number the sections and sub-sections.
I know that (sadly) Markdown does not support this, and I know it's painful to do manually. But it's more painful not to be able to say "In section 2.2 ....".
There was a problem hiding this comment.
This sounds like a job for five lines of elisp... :-)
There was a problem hiding this comment.
I wrote the 20 lines of elisp that were required, and it works, but on further reflection, I'm a bit hesitant to impose bureaucratic maintenance requirement on further editors of a document. It might be best to just chalk this up to the limitations of Markdown, rather than constantly fighting the format.
There was a problem hiding this comment.
For what it's worth, I tend to agree with @david-christiansen here. I agree that section numbers would be great. But I believe that they become a maintenance burden. One possible route forward is to switch to reStructuredText, which support section numbers natively, but is a less common format.
|
|
||
| ## Purpose | ||
|
|
||
| The HF Technical Track is an experienced group of people with knowledge of the Haskell ecosystem, responsible for the strategic technical direction on behalf of the Haskell Foundation. HFTT members should be either individuals responsible for a specific part of the Haskell ecosystem, or contributors and committers to parts of it. | ||
| The purpose of the TWG is to assess technical proposals on their merits, and to recommend whether the Haskell Foundation should devote resources to particular projects. The members of the TWG are an experienced group of people with knowledge of the Haskell ecosystem, responsible for the strategic technical direction on behalf of the Haskell Foundation. TWG members should be either individuals responsible for a specific part of the Haskell ecosystem, or contributors and committers to parts of it. |
There was a problem hiding this comment.
Is it worth clarifying "should"? I think it's easy to misinterpret this to say that an approved proposal "should" get funding. My understanding is that an approved proposal may get funding -- but it also might not, depending on the priorities set by the HF independently of the TWG.
| @@ -23,12 +23,12 @@ HFTT Members are tasked with the following responsibilities: | |||
|
|
|||
| None. | |||
|
|
|||
| The HFTT may make decisions regarding accepted technical projects. The Delegated Authority shall arrange budgetary or resource requests as needed, based on the outcome of decisions made by the HFTT, with the budget committee and Executive Director of the HF. | |||
| The TWG may make decisions regarding accepted technical projects. The Delegated Authority shall arrange budgetary or resource requests as needed, based on the outcome of decisions made by the TWG, with the budget committee and Executive Director of the HF. | |||
There was a problem hiding this comment.
Is it worth keeping the "Delegated Authority" abstraction? I know you're keen to simplify things, and there may be an opportunity for simplification here.
| - Changes to HFTT membership require simple majority approval | ||
| - 1 Delegated authority and 8 general members shall be required for a functioning HFTT | ||
| - Changes to TWG membership require simple majority approval by the members of the TWG | ||
| - 1 Delegated authority and 8 general members shall be required for a functioning TWG | ||
| - No one may serve two terms consecutively, except for the CTO/delegated authority. |
There was a problem hiding this comment.
"CTO" terminology now out of date.
| - No one may serve two terms consecutively, except for the CTO/delegated authority. | ||
| - Elections *must* be held such that there is no period when the HFTT is not at full membership | ||
| - Elections *must* be held such that there is no period when the TWG is not at full membership. In case of resignations, elections shall be held as soon as reasonably possible. |
There was a problem hiding this comment.
| - Elections *must* be held such that there is no period when the TWG is not at full membership. In case of resignations, elections shall be held as soon as reasonably possible. | |
| - Elections *must* be held such that there is no period when the TWG is not at full membership. In case of resignations that drive membership below 8, elections shall be held as soon as reasonably possible. |
| In order to become a member, one must apply at election time, and be elected to the TWG. With the exception of the first iteration of the TWG, all members are elected by means of the election process. | ||
|
|
||
|
|
||
| ## Proposal Voting Procedure | ||
|
|
||
| Ranked voting is used, with the following criteria required for each status: | ||
|
|
There was a problem hiding this comment.
What if none of these happens? That is, if a vote for acceptance fails, then what?
|
|
||
| ### Proposal Size | ||
|
|
||
| There is no size floor or ceiling for project submissions. Each HFTP will be weighed against the existing resource pool to decide whether a proposal is ready for acceptance. In particular, small quality of life proposals are as welcome as epic community-shifting proposals - we do not judge. However, this is why step 1 (informal discussion) is so important: often, it may be faster and easier to just make that Pull Request and find people who are free to do it with you! If, for some reason, the discovery and discussion phase does not catch these issues, it will be raised by HFTT members when appropriate. When a proposal, big or small, is inappropriate for the venue, we will be sure to make it known. | ||
| There is no size floor or ceiling for project submissions. In particular, small quality of life proposals are as welcome as epic community-shifting proposals - we do not judge. However, this is why step 1 (informal discussion) is so important: often, it may be faster and easier to just make that Pull Request and find people who are free to do it with you! If, for some reason, the discovery and discussion phase does not catch these issues, it will be raised by TWG members when appropriate. When a proposal, big or small, is inappropriate for the venue, we will be sure to make it known. |
There was a problem hiding this comment.
"that Pull Request": what is this referring to?
|
|
||
| ### Acceptance | ||
|
|
||
| Upon acceptance, an HFTP is merged into the repository by an HFTT member, and the HFTP is assigned a shepherd from the HFTT. A shepherd is chosen at random, and will serve as a liason for the project, guiding its progress. Shepherds are required to report dutifully and accurately on the progress at the bi-weekly HFTT standup meetings. Project leaders are welcome to arrange alternative reporting schema (e.g. as their schedules allow, or if time off is required) upon request, as long as reports are given on a consistent basis. | ||
| Upon acceptance, an HFTP is merged into the repository by an TWG member, and the HFTP is assigned a shepherd from the TWG who will serve as a liason for the project, guiding its progress. Shepherds are required to report dutifully and accurately on the progress to the TWG. Project leaders are welcome to arrange alternative reporting schema (e.g. as their schedules allow, or if time off is required) upon request, as long as reports are given on a consistent basis. |
There was a problem hiding this comment.
This step is surprising to me. The charter says that the TWG is meant to decide upon ("assess") proposals. But this shepherding process seems to be more about delivering the goals of proposals. Is that also under the remit of the TWG? Perhaps so, but reading these documents, it looks like this status is a bit ambiguous.
|
|
||
| Authors are responsible for building consensus within the community and documenting dissenting opinions before the HFTP is officially discussed by the HFTT. Their goal is to convince the HFTT that their proposal is useful and addresses pertinent problems in the Haskell ecosystem as well as interactions with already existing features. Authors can change over the life-cycle of the HFTP. For a formal charter, as well as a list of current HFTT members, please see [CHARTER.md](CHARTER.md). | ||
| Authors are responsible for building consensus within the community and documenting dissenting opinions before the HFTP is officially discussed by the TWG. Their goal is to convince the TWG that their proposal is useful and addresses pertinent problems in the Haskell ecosystem as well as interactions with already existing features. Authors can change over the life-cycle of the HFTP. For a formal charter, as well as a list of current TWG members, please see [CHARTER.md](CHARTER.md). |
There was a problem hiding this comment.
This section seems more about the role of authors than of the TWG.
| - Postponed (needs a simple majority, an HFTT member that voted to postpone will close the issue and PR, and write clear conditions for reopening) | ||
| - Revision needed (needs a simple majority. This can only be the outcome of the vote four times, for a total of five rounds. An HFTT member will write up what revisions are needed.) | ||
| - Rejected (needs 66% of the HFTT to vote in favor) | ||
| - Accepted (needs 66% of the TWG to vote in favor, and the HFTP must specify a proposal lead, e.g. an implementor or project director, from the TWG who will represent the work done on the project.) |
There was a problem hiding this comment.
Is a proposal lead the same as a shepherd? And must this person be on the TWG?
| - Dormant (needs a simple majority, an TWG member that voted in favor will close the issue and PR and mark it as Dormant) | ||
| - Postponed (needs a simple majority, an TWG member that voted to postpone will close the issue and PR, and write clear conditions for reopening) | ||
| - Revision needed (needs a simple majority. This can only be the outcome of the vote four times, for a total of five rounds. An TWG member will write up what revisions are needed.) | ||
| - Rejected (needs 66% of the TWG to vote in favor) |
There was a problem hiding this comment.
I could be wrong, but this voting process looks like it has corner cases where no decision, at all, is reached.
|
Thanks for all the feedback - I'm going to work on a revision, and I'll get back with it. |
|
I think #36 makes this irrelevant. I've done my best to incorporate feedback here into the new document. |
As discussed via email, I'd like to update a few things here and am interested in knowing what you think.
Here's a summary of the changes:
Given that our problem is more lack of proposals than too many, we can also consider simplifying the formality of the proposal process. I'll save that for another round.