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

Update RFC process, add blog post blurb section to RFC template #1750

Merged
merged 12 commits into from Oct 30, 2018

Conversation

Projects
None yet
6 participants
@kuychaco
Member

kuychaco commented Oct 19, 2018

Update the "New features" section with modifications to the RFC process per discussion with @smashwilson and @vanessayuenn. Namely, state purpose of using RFC process, expectation that RFC be updated throughout development, and improved merge criteria based on our past experience using the RFC process.

Also added a new section to the RFC template "Feature description for Atom release blog post"

kuychaco and others added some commits Oct 19, 2018

Update how-we-work to capture RFC process modifications discussed
Co-Authored-By: Ash Wilson <smashwilson@gmail.com>
Co-Authored-By: Vanessa Yuen <vanessayuenn@users.noreply.github.com>
State what goals of RFC are and are not
Co-Authored-By: Ash Wilson <smashwilson@gmail.com>
Co-Authored-By: Vanessa Yuen <vanessayuenn@users.noreply.github.com>

@kuychaco kuychaco changed the title from Update how-we-work to capture RFC process modifications discussed to Update RFC process, add blog post blurb section to RFC template Oct 19, 2018

@coveralls

This comment has been minimized.

coveralls commented Oct 19, 2018

Coverage Status

Coverage increased (+3.2%) to 84.932% when pulling 1ae716f on rfc-process into 27f944a on master.

Show resolved Hide resolved docs/how-we-work.md Outdated
Show resolved Hide resolved docs/rfcs/000-template.md Outdated
@simurai

I'm a bit on the fence with keeping the RFC open until it's shipped. But we can give it a try and see how it turns out.

Show resolved Hide resolved docs/how-we-work.md Outdated
The goal is to suss out important considerations and valuable ideas as early as possible and encourage more holistic / bigger picture thinking. The goal is NOT to flesh out the perfect design or come to complete consensus before we start building.
Development work on the feature may start at any point once the RFC pull request has been opened with a description of the feature. The RFC is merged once the feature work is merged.

This comment has been minimized.

@simurai

simurai Oct 20, 2018

Member

The RFC is merged once the feature work is merged.

This will be interesting to try out. I kinda liked merging RFCs early to symbolize that the team mostly agrees on the direction.

This comment has been minimized.

@annthurium

annthurium Oct 20, 2018

Contributor

oh, I missed this. Interesting. I'm not opposed to it, but do you have any tips on remembering to merge RFCs? I have a feeling I'm going to forget.

This comment has been minimized.

@smashwilson

smashwilson Oct 22, 2018

Member

I kinda liked merging RFCs early to symbolize that the team mostly agrees on the direction.

This is one of the big problems we were seeing with the existing process, though. Nobody wants to be the one who says "that's it, the design is 'done', let's get started building," so they languish. Also, there's a strong feedback loop between design and implementation, especially when it comes to UX concerns. Lots of things will look good in markdown but "feel" wrong in practice, so the design evolves naturally as we build it, and we spend less time on things we don't build.

We were hoping to alleviate this by leaving RFCs at a bit higher level of abstraction, but it's challenging to separate which points are "details we can work out later" versus "intrinsic properties we should agree on up front."

This comment has been minimized.

@kuychaco

kuychaco Oct 23, 2018

Member

do you have any tips on remembering to merge RFCs? I have a feeling I'm going to forget.

Yeah I had this thought too. I figure the RFC PR will be listed in our project board, and that will serve as a good reminder. How does that sound @annthurium?

One benefit to keeping the RFC PR open until the end is that once development is complete we can make nice gifs and add them to blog post section of the RFC. That can be the final action item before we merge the RFC PR.

And yeah, defining some level of RFC done-ness prior to actually shipping the feature into master I think will be super arbitrary and therefore hard to settle on. And I think there's value in letting the RFC remain alive and evolving as the development process surfaces new information and considerations.

This comment has been minimized.

@smashwilson

smashwilson Oct 29, 2018

Member

As a data point, there's still stuff in RFC-001 we haven't gotten around to doing yet.

I'm kind of thinking of it as "we merge the RFC PR when we, the core team, move on to something else and aren't working on it directly for a while," rather than when we hit some "completeness" threshold? Put another way - I think that us starting to work on new things is a good, emergent, arbitrary way for us to call a feature "shipped", even if there's still stuff in the document that we haven't gotten to yet.

@smashwilson

👍

Show resolved Hide resolved docs/how-we-work.md Outdated
The goal is to suss out important considerations and valuable ideas as early as possible and encourage more holistic / bigger picture thinking. The goal is NOT to flesh out the perfect design or come to complete consensus before we start building.
Development work on the feature may start at any point once the RFC pull request has been opened with a description of the feature. The RFC is merged once the feature work is merged.

This comment has been minimized.

@smashwilson

smashwilson Oct 22, 2018

Member

I kinda liked merging RFCs early to symbolize that the team mostly agrees on the direction.

This is one of the big problems we were seeing with the existing process, though. Nobody wants to be the one who says "that's it, the design is 'done', let's get started building," so they languish. Also, there's a strong feedback loop between design and implementation, especially when it comes to UX concerns. Lots of things will look good in markdown but "feel" wrong in practice, so the design evolves naturally as we build it, and we spend less time on things we don't build.

We were hoping to alleviate this by leaving RFCs at a bit higher level of abstraction, but it's challenging to separate which points are "details we can work out later" versus "intrinsic properties we should agree on up front."

We use a lightweight RFC (request for comments) process to ensure that folks have an opportunity to weigh in on design, alternatives, drawbacks, questions, and concerns. It provides a quick and easily scannable summary of what was discussed and decided.
The goal is to suss out important considerations and valuable ideas as early as possible and encourage more holistic / bigger picture thinking. The goal is NOT to flesh out the perfect design or come to complete consensus before we start building.

This comment has been minimized.

@smashwilson

smashwilson Oct 22, 2018

Member

👍 💯

@@ -72,6 +72,18 @@ Major, cross-cutting refactoring efforts fit within this category. Our goals wit
To introduce brand-new functionality into the package, follow this guide.
##### On using RFCs
We use a lightweight RFC (request for comments) process to ensure that folks have an opportunity to weigh in on design, alternatives, drawbacks, questions, and concerns. It provides a quick and easily scannable summary of what was discussed and decided.

This comment has been minimized.

@smashwilson

smashwilson Oct 23, 2018

Member

One more thing that caught my eye:

Suggested change Beta
We use a lightweight RFC (request for comments) process to ensure that folks have an opportunity to weigh in on design, alternatives, drawbacks, questions, and concerns. It provides a quick and easily scannable summary of what was discussed and decided.
We use an RFC (request for comments) process to ensure that folks have an opportunity to weigh in on design, alternatives, drawbacks, questions, and concerns. It provides a quick and easily scannable summary of what was discussed and decided.

Calling our own RFC process "lightweight" feels like calling our software "simple" in the README - lightweight-ness is in the eye of the beholder 😉 We want it to be lightweight, but maybe we shouldn't just say that it is... ?

This comment has been minimized.

@kuychaco

kuychaco Oct 23, 2018

Member

Heh yeah I hear you. I was trying to find a way to make RFC sound more approachable. I think the term "RFC" itself sounds intimidating and it could be reassuring to have some other descriptive word to keep people's imagination from making it bigger and scarier than it really is. But yeah, everything is relative and we can't objectively call this lightweight. I'm fine taking it out. Perhaps you have another suggestion for how to convey to folks that the scope isn't this super formal daunting thing that might deter them?

This comment has been minimized.

@smashwilson

smashwilson Oct 29, 2018

Member

I liked @vanessayuenn's suggestions about renaming it from "RFC" to something like "feature proposal" as a way to sound less daunting.

I do think there is a limit to how approachable we can make "write a bunch of markdown before you get to do the fun code," regardless of how we word it 😉

kuychaco added some commits Oct 29, 2018

@smashwilson

Looks like there's one section with a partially written sentence 😄

Other than that, I'm on board with merging 👍

@@ -72,6 +72,18 @@ Major, cross-cutting refactoring efforts fit within this category. Our goals wit
To introduce brand-new functionality into the package, follow this guide.
##### On using RFCs
We use a lightweight RFC (request for comments) process to ensure that folks have an opportunity to weigh in on design, alternatives, drawbacks, questions, and concerns. It provides a quick and easily scannable summary of what was discussed and decided.

This comment has been minimized.

@smashwilson

smashwilson Oct 29, 2018

Member

I liked @vanessayuenn's suggestions about renaming it from "RFC" to something like "feature proposal" as a way to sound less daunting.

I do think there is a limit to how approachable we can make "write a bunch of markdown before you get to do the fun code," regardless of how we word it 😉

The goal is to suss out important considerations and valuable ideas as early as possible and encourage more holistic / bigger picture thinking. The goal is NOT to flesh out the perfect design or come to complete consensus before we start building.
Development work on the feature may start at any point once the RFC pull request has been opened with a description of the feature. The RFC is merged once the feature work is merged.

This comment has been minimized.

@smashwilson

smashwilson Oct 29, 2018

Member

As a data point, there's still stuff in RFC-001 we haven't gotten around to doing yet.

I'm kind of thinking of it as "we merge the RFC PR when we, the core team, move on to something else and aren't working on it directly for a while," rather than when we hit some "completeness" threshold? Put another way - I think that us starting to work on new things is a good, emergent, arbitrary way for us to call a feature "shipped", even if there's still stuff in the document that we haven't gotten to yet.

##### FAQ
Q: Why not just use issues?
In the past we've used issues for these discussions and the issue body quickly becomes outdated by discussion in comments and it's hard to

This comment has been minimized.

@smashwilson

smashwilson Oct 29, 2018

Member

🚨 Sentence fragment! 😆 🚨

@@ -1,3 +1,9 @@
<!---
For community contributors -- Please fill out Part 1 of the following template. This will help our team collaborate with you and give us an opportunity to provide valuable feedback that could inform your development process. Sections in Part 2 are not mandatory to get the conversation started, but will help our team understand your vision better and allow us to give better feedback.

This comment has been minimized.

@smashwilson

smashwilson Oct 29, 2018

Member

💯 Excellent.

kuychaco and others added some commits Oct 30, 2018

Tweak merge criteria based on @smashwilson's comment
> I'm kind of thinking of it as "we merge the RFC PR when we, the core team, move on to something else and aren't working on it directly for a while," rather than when we hit some "completeness" threshold? Put another way - I think that us starting to work on new things is a good, emergent, arbitrary way for us to call a feature "shipped", even if there's still stuff in the document that we haven't gotten to yet.

Co-Authored-By: Ash Wilson <smashwilson@gmail.com>
RFC --> Feature Request
Co-Authored-By: Vanessa Yuen <vanessayuenn@users.noreply.github.com>
Emojify RFC template 😄
Co-Authored-By: Vanessa Yuen <vanessayuenn@users.noreply.github.com>
Add why we use pull requests instead of issues for Feature Requests
Co-Authored-By: Ash Wilson <smashwilson@gmail.com>

@kuychaco kuychaco merged commit 08e3094 into master Oct 30, 2018

7 checks passed

ci/circleci: beta Your tests passed on CircleCI!
Details
ci/circleci: dev Your tests passed on CircleCI!
Details
ci/circleci: snapshot Your tests passed on CircleCI!
Details
ci/circleci: stable Your tests passed on CircleCI!
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
coverage/coveralls Coverage increased (+3.2%) to 84.932%
Details

@kuychaco kuychaco deleted the rfc-process branch Oct 30, 2018

@vanessayuenn vanessayuenn referenced this pull request Nov 21, 2018

Closed

v0.23.0-0 QA Review #1806

5 of 5 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment