Define a process for feature proposals (RFCs) about project HOT 21 CLOSED

The RFC process needs to be formalized and transparent so that no one puts in work in creating an RFC and then having it get stuck in "limbo" because of the SC or Moderators/Collaborators.

I propose the following:

• RFCs added in as an issue on this repo with the tag "RFC". I'm divided on if we should have it on Discourse instead/also. On one hand, I like Discourse's format better, but that might be more "user facing" than an RFC needs to be.
• Within 1 week a SC member will be assigned to it. It will be brought up in the next SC meeting. The assignee is responsible for moving it through the committee.
• During the meeting, SC members will decide if they want to go forward with it and/or assign someone to take charge of it. It could be the person proposing the RFC, a collaborator, or someone else outside the org. In the case that it is someone outside the org, a member of the SC or Collaborator should also be assigned to it.
• The SC member or Collaborator will have final responsibility in taking charge of the change.

If we wanted to have formalized RFCs, we would need different formats for the following:

• Hardware
• Software
• Combination Hardware/Software. Or maybe just 2 RFCs?

I don't think we should have required formats, but I do think we should provide examples. The Software example can be my wifi-cc3000 example. I can create other example ones for hardware (an existing module as an example, or the soil/moisture module) or hardware/software combos (reach?).

from project.

I think posting as an issue here should be the only requirement. On the Rust forums, people often post "pre-RFCs" for general discussion before they are formalized, which we can leave optional.

Assignment by an SC member should be ASAP, tagged with sc-agenda, and it can be discussed at the next meeting. I agree with your stewardship criteria.

I'd actually disagree about not having a required format; I think asking the right questions is important. I propose a simple template with [ software ] and [ hardware ] sub-sections, either of which can be omitted.

I was wondering how much overlap this has with a specification; the spec I wrote for the Build Server has Vision, Background, Scenarios, Dependencies, Goals, Features, and Success Metrics. I would want any feature work to have all of those, but writing a good spec is more Project Management than proposal. How much would we expect a contributor to flesh that out, versus the SC? Would we generate a separate spec after an RFC? Or can we combine them somehow?

from project.

I agree with @jiahuang about the process being very formal and immediate.

I don't think we need RFC templates to begin with (I'm on board with good examples). Partially, because I imagine the process of designing/implementing features for the CLI vs firmware vs openWRT vs modules vs new Tessels would all be very different. And partially because I think it's important to keep the overhead of the project low in order to encourage the most contribution. If the SC thinks that RFCs aren't detailed enough or are often lacking a specific section, they can add a formal template as necessary.

from project.

Asking questions via a guided template may lower contribution. I worry that the alternative, unstructured proposals, can hinder collaboration by not properly assessing what the goal and tradeoffs of adding a feature is.

When work is asychronous and distributed, it helps to have as much information as possible so that it can be worked on without diligent stewardship. I don't find it unreasonable for people to propose ideas super informally on the forums, but us to adopt a strong preference for scoped, detailed, and coherent ideas when it's submitted and ready to be worked on. And I think this can be done in just a couple of questions, tops.

from project.

I think that the job of the SC/Collaborators is to pull out as much information as possible. The barrier to proposing a change should be as little as possible and all of the mechanisms for ensuring a robust code base and feature set should be the responsibility of the SC/Collaborators.

from project.

I agree that SC members should be responsible for ensuring a feature or proposal succeed by determining its requirements and feature set. But I think an RFC process that doesn't address requirements and feature set is not a useful process. For example,

1. A Wifi API is written as a proposal as a description
2. It is submitted as an RFC
3. The RFC is accepted
4. A specification now has to be written to determine details, interpreting the meaning of the given description
5. We may then discover the feature is not possible, the resources are too great to invest in, or there are conflicts in implementing the feature

Essentially, I worry about "accepting" a feature e.g. "Create a new API for Neopixels" without specifying in detail what it takes to accomplish that. It sounds like a very difficult process to manage, especially if we've publicly committed to the idea and find we can't deliver on it or that it actually would hurt the project.

My alternate proposal: We have informal discussion and voting on the forums under a "feature" tag. This is the lowest barrier to entry for a community member wanting to submit an idea. Given enough interest, popular topics can be championed and written as a detailed Specification by a Collaborator, which can formally be discussed, accepted, or rejected during an agenda meeting.

from project.

But I think an RFC process that doesn't address requirements and feature set is not a useful process

Agreed, this is why the SC/Collaborators would be required to ask all the questions necessary to have the feature and spec fully defined.

Given enough interest, popular topics can be championed and written as a detailed Specification by a Collaborator, which can formally be discussed, accepted, or rejected during an agenda meeting.

There are things I like and things I don't like about this proposal. I don't like that it adds more formality to contribution which would deter new entrants. It's more for them to learn. I also don't like that the design decisions are taken out of their hands. As someone coming into an open source project, if I decided to contribute, I would want to be involved at every step and have the recognition that comes with designing a new part of a system. I do like that it makes a feature more likely to be built and it can be relieving for some less experienced contributors who may only know that a feature should be added and not how it's built. In short, I think this method optimizes progress on the project, but not collaboration.

from project.

I also don't like that the design decisions are taken out of their hands. As someone coming into an open source project, if I decided to contribute, I would want to be involved at every step and have the recognition that comes with designing a new part of a system.

Okay, I can see the rationale for splitting off "design decisions" from "what needs to get done".

Again, I just want to avoid accepting an RFC on its own, seeing it's infeasible or impractical, and then having to reneg on implementing it.

We can make an RFC process that is a) informal and b) ensures all the "design decisions" remain in the hands of the contributor. Then a subsequent spec process selects for the ideas we go forward with, adds structure, and is the actual document voted on by the SC. This would be strictly additive and leave all the minutae of project management to us, while empowering the contributor to submit and steward their features without much effort.

from project.

Again, I just want to avoid accepting an RFC on its own, seeing it's infeasible or impractical, and then having to reneg on implementing it.

This is easily avoided by not accepting an RFC until it has been proven to be feasible. The members of the SC should be able to identify when an RFC is ready and we could even have a document that outlines all the questions that need to be answered.

Then a subsequent spec process selects for the ideas we go forward with, adds structure, and is the actual document voted on by the SC.

I don't quite understand what you mean. My understanding of what you're proposing is the following:

1. Community member suggests a feature
2. SC poses insightful question that the OP and community can chime in on
3. When the feature is fully flushed out, the SC extracts all of the information from that thread into a formal document.
4. The SC manages the project

Is that correct?

from project.

The members of the SC should be able to identify when an RFC is ready and we could even have a document that outlines all the questions that need to be answered.

In my mind, that would be literally every question in a Specification. Is that complexity we are trying to avoid having a contributor have to answer?

Is that correct?

That sounds about right. I don't think a community member describing a feature in isolation is enough to generate a formal document though. If the contributor is just discussing a feature's design, then their contribution lacks a timetable, the resources required, immediate and long term steps, and a support story. So in my suggestion, it is up to the SC to append those sections to a contributor's feature proposal. Then the SC votes on that formalized document as a whole (not just the contributor's original design).

from project.

Looking at the spec you linked to, I actually think it wouldn't be so deterring for a contributor to just address:

• Vision
• Background
• Use Cases
• Dependencies
• Success Metrics

I was originally thinking of the gigantic specs we made for Tessel 2 but this seems much more reasonable.

I agree about having the SC build out the infrastructure and project management resources to get it down following acceptance.

from project.

We have informal discussion and voting on the forums under a "feature" tag.

I like the idea of bringing on more members of the community as early as possible.

We may also want to draw a line on which things constitute RFCs that are suitable for the SC to handle. Are there situations (besides "I need tessel to do x") that are not RFC-worthy? Or is it basically any 3rd party tool can be formalized as an RFC? Or only parts that touch core firmware?

Using your examples, if I were a 3rd party developer, I would not think that a neopixels lib is RFC-able.

from project.

After some more discussion today, @Frijol and I came to a consensus that after the spec is flushed out and formalized by a contributor on the Forums, that Contributor should open up issues on all relevant Github repos and then make a checklist of all of those issues on the original Forum post. Each Github issue should also have a link back to the Forum post.

from project.

@johnnyman727 Can you expand what an "issue" is here? Or augment my understanding of the following process:

• User makes a feature proposal on a forum
• Collaborator helps champion that idea
• Collaborator submits it as an RFC on an rfcs repo, expanding out all those sections you mentioned here
• RFC is voted on by SC

from project.

An Issue here is an actual Github Issue.

Your understanding isn't quite right based on what @Frijol and I proposed. There is no RFCs repo. The RFC lives on the Forum thread. Github Issue(s) are opened on relevant Github repositories and linked back to the RFC Thread. The RFC Thread also contains a checklist of all opened Github Issues.

from project.

The process that Ecma/TC39 has adopted for new JS language feature development has brought drastic improvements in both utility and community involvement. Here's a run down of that process:

• One or more champions propose a new feature by creating a repo dedicated to that feature
  • Examples:
    • https://github.com/rwaldron/exponentiation-operator
    • https://github.com/wycats/javascript-decorators
  • The feature is free to describe all aspects of the platform that it interacts with.
  • The feature is described as thoroughly as possible in the readme.md of the repo.
  • Feedback, discussion and development of the proposal is done by filing issues and pull requests. This ensures that all of the history of a particular feature is preserved.
    • Example: wycats/javascript-decorators#12
  • Additions and modifications to the feature's proposal are contributed as pull requests (again, great historic record here)
    • Example: https://github.com/arv/ecmascript-object-observe/pull/12/files
  • The repo may include reference implementations, tests, API mockups, use cases, diagrams, illustrations, presentations, pdfs, slide decks, etc. The idea is that the "art" is preserved in a single location.
    • Example: https://github.com/tc39/Array.prototype.includes/tree/master/reference-implementation
  • Using a repo is convenient for adding and removing fellow feature contributors
  • Issues allow creating trackable bullet lists of action items, these are useful for defining milestones
    • Example: https://github.com/rwaldron/exponentiation-operator/issues
• Each proposal is presented in 4 stages, defined in a publicly accessible process document
  • Example: https://docs.google.com/document/d/1QbEE0BsO4lvl7NFTn5WXWeiEIBfaVUF7Dk0hpPpPDzU/edit
• The feature proposal is added to a central repo that keeps a public record of the feature's current stage
  • Example: https://github.com/tc39/ecma262
• Each stage of progress is presented to the committee at one of the bi-monthly meetings (this can obviously be done is shorter cycles). The feature either advances to the next stage or continues being developed at the current stage, incorporating new feedback.
• Once the feature is complete, it's promoted to the specification. This is obviously substituted with "feature is merged".

from project.

I'm a fan of this process. My only suggestion would be that we encourage folks making these RFCs to post a link on the Forums to include as many people as possible. @tcr @Frijol what are your thoughts?

from project.

Agreed, and +1 to the cross-post to the forums– make the community aware of it but direct the conversation over to somewhere better at detailed discussion

from project.

My proposal from that:

• All feature proposals are forked from a tessel/rfcs repo (this is the rust model)
• All issue discussion and PRs can happen on that forked repo itself. E.g. tessel/rfcs -> tcr/wifi-rfc, that's the source for discussion
• We only have two stages, for simplicity; pre-merge and post-merge. Issues should be brought up on the PR into tessel/rfcs, but handled on the original repo

Rest is similar. Will post a more formalized suggested process post-SC meeting

from project.

My only suggestion would be that we encourage folks making these RFCs to post a link on the Forums to include as many people as possible. @tcr @Frijol what are your thoughts?

Yes, champions should do their best to build support for a feature proposal in any way that they can :)

@tcr

All feature proposals are forked from a tessel/rfcs repo (this is the rust model)
All issue discussion and PRs can happen on that forked repo itself. E.g. tessel/rfcs -> tcr/wifi-rfc, that's the source for discussion
We only have two stages, for simplicity; pre-merge and post-merge. Issues should be brought up on the PR into tessel/rfcs, but handled on the original repo

+1 to all (the number of stages irrelevant, just that the stages are well defined)

from project.

Codified into tessel/rfcs#1.

from project.